simple-circuit-engine 0.0.11 → 0.0.13

package/dist/scene/static/tools/BuildTool.d.ts

@@ -0,0 +1,290 @@
+import { IEditingTool, ToolType, CursorType } from '../../shared/types';
+import { CircuitController } from '../CircuitController';
+/**
+ * Build Tool Implementation
+ * @module scene/static/tools/BuildTool
+ *
+ * Unified tool for all circuit editing operations:
+ * - Wire creation between endpoints
+ * - Element positioning (components, branching points, wire points)
+ * - Component rotation
+ * - Element deletion
+ * - Branching point creation
+ * - Component placement & addition (add_component mode with picker widget)
+ *
+ * Replaces old: PositionTool, WireTool, DeleteTool, BranchingPointTool, AddComponentTool
+ */
+import * as THREE from 'three';
+/**
+ * Unified tool for building circuits
+ * Implements all circuit editing functionality in a single tool
+ */
+export declare class BuildTool implements IEditingTool {
+    readonly type: ToolType;
+    private _controller;
+    private mode;
+    private lastCancelledOp;
+    private lastOperationCompletedTs;
+    private wireCreationState;
+    private wireDragState;
+    private componentDragState;
+    private bpDragState;
+    private clipboard;
+    private pickerWidget;
+    private ghostPreview;
+    private hasOverlap;
+    private pickerSelection;
+    /**
+     * Construct a new BuildTool instance
+     * @param controller - The circuit scene controllerType instance
+     */
+    constructor(controller: CircuitController);
+    /**
+     * Activate build tool and set up event listeners
+     * Resets all tool state and attaches DOM event handlers
+     */
+    onActivate(): void;
+    /**
+     * Deactivate build tool and clean up event listeners
+     * Cancels any active operations and removes all event handlers
+     */
+    onDeactivate(): void;
+    /**
+     * Forward a language change to the component picker.
+     */
+    setLanguage(lng: string): void;
+    /**
+     * Cancel current ongoing operation : can be called from outside if needed
+     */
+    cancelOperation(): void;
+    /**
+     * Get the current cursor type for this tool
+     * Returns cursor based on current mode and hover state
+     */
+    getCursorType(): CursorType;
+    /**
+     * Get preview objects to render in the scene
+     * Returns array of preview objects currently visible
+     */
+    getPreviewObjects(): THREE.Object3D[];
+    /**
+     * Handle pointer down event
+     * Routes to appropriate operation based on hover target and state
+     */
+    private handlePointerDown;
+    /**
+     * Handle pointer up event
+     *
+     * Ends current operation, commits final positions to the circuit model,
+     * and re-enables camera controls.
+     *
+     * Completes current operation based on mode
+     */
+    private handlePointerUp;
+    /**
+     * Handle grid position move event according to ongoing mode
+     * Updates preview or drag position during active operations
+     */
+    private handleGridPositionMove;
+    /**
+     * Handle keyboard events
+     * Supports Escape (cancel), Delete/Backspace (delete), R (rotate), Ctrl+C (copy), Ctrl+V (paste)
+     */
+    private handleKeyDown;
+    /**
+     * Handle double-click events
+     * Routes to rotation (component) or branching point creation (wire/empty)
+     */
+    private handleDblClick;
+    /**
+     * Operations lifecycle methods
+     * (start, update, cancel, complete)
+     */
+    /**
+     * Start wire creation from source enode
+     * @param sourceEnodeId - Source enode ID
+     */
+    private startWireCreation;
+    /**
+     * Update wire creation preview with new target position
+     * @param position
+     * @private
+     */
+    private updateWireCreation;
+    /**
+     * Cancel wire creation and reset state
+     */
+    private cancelWireCreation;
+    /**
+     * Complete wire creation between source enode and :
+     * - existing target enode if it is hovered
+     * - new branching point on wire if target is a wire
+     * - new branching point if target is null
+     * @param hoveredElement - Currently hovered element at wire creation end
+     */
+    private completeWireCreation;
+    /**
+     * Start wire dragging operation
+     * @param wireId - Wire being dragged
+     * @param targetType - Type of drag target
+     * @param pointIndex - Index of intermediate point, or -1 for new/branching
+     * @param worldPosition - Initial position
+     */
+    private startWireDrag;
+    /**
+     * Update drag target position during drag
+     * @param worldPosition - Current cursor position in world space
+     */
+    private updateWireDrag;
+    /**
+     * Cancel wire drag operation and revert to original positions
+     */
+    private cancelWireDrag;
+    /**
+     * Commit drag operation and persist changes
+     */
+    private completeWireDrag;
+    /**
+     * Start component dragging operation
+     * @param componentId - UUID of the component being dragged
+     * @param worldPosition - Initial position
+     */
+    private startComponentDrag;
+    /**
+     * Update component visual position during drag
+     * @param worldPosition - Current cursor position in world space
+     */
+    private updateComponentDrag;
+    /**
+     * Cancel component drag operation and revert to original positions
+     */
+    private cancelComponentDrag;
+    /**
+     * complete component drag operation and persist changes
+     */
+    private completeComponentDrag;
+    /**
+     * Start branching point dragging operation
+     * @param enodeId - UUID of the branching point being dragged
+     * @param worldPosition - Initial position
+     */
+    private startBPDrag;
+    /**
+     * Update branching point position during drag
+     * @param worldPosition - Current cursor position in world space
+     */
+    private updateBPDrag;
+    /**
+     * Cancel branching point drag operation and revert to original positions
+     */
+    private cancelBPDrag;
+    /**
+     * Commit branching point drag operation and persist changes
+     */
+    private completeBPDrag;
+    /**
+     * private helpers
+     */
+    /**
+     * Create a standalone branching point at empty grid position (T048)
+     * @param worldPosition - 3D position in world space
+     */
+    private createStandaloneBranchingPoint;
+    /**
+     * Create a branching point on an existing wire, splitting it (T044)
+     * @param wireId - Wire to split
+     * @param worldPosition - 3D position in world space
+     */
+    private createBranchingPointOnWire;
+    /**
+     * Check if hoveredElement is a valid wire target during wire creation
+     * @param hoveredElement - Current hovered element or null
+     * @returns True if target is valid for wire endpoint
+     */
+    private isValidWireTarget;
+    /**
+     * Rotate a component 90° clockwise
+     *
+     * Updates both the circuit model and visual representation.
+     * Emits componentRotated event to notify listeners.
+     * Only works on selected components (not wires or enodes).
+     */
+    private rotateComponent;
+    /**
+     * Check if wire intermediate point should be merged or deleted
+     * Returns updated positions array after merge/delete check
+     * @param wire - Wire being modified
+     * @returns Final intermediate positions array
+     */
+    private checkMergeDelete;
+    /**
+     * Copy component type and rotation to clipboard
+     * @param componentId - UUID of the component to copy
+     */
+    private copyComponent;
+    /**
+     * Paste component from clipboard at hovered position
+     * Creates a new component with the type and rotation from clipboard
+     */
+    private pasteComponent;
+    /**
+     * Cycles the sourceType of an enode: null → Voltage → Current → null
+     * Updates both model and visual immediately.
+     * @param enodeId - UUID of the enode to cycle
+     * @param hitbox - hitbox of the enode being clicked
+     */
+    private cycleEnodeSourceType;
+    /**
+     * Open config panel for component (T014)
+     * Converts component world position to screen coordinates and opens panel
+     * @param componentId - UUID of the component to configure
+     * @param event - Mouse event for screen position
+     */
+    private openConfigPanel;
+    /**
+     * Enter add_component mode: open the picker widget and listen for cursor movement
+     * @param event - Mouse event (used for widget positioning)
+     */
+    private enterAddComponentMode;
+    /**
+     * Exit add_component mode: close widget, dispose ghost, return to idle
+     */
+    private exitAddComponentMode;
+    /**
+     * Called when user selects or deselects an item in the picker widget
+     */
+    private onPickerSelectionChange;
+    /**
+     * Place the currently selected item (component or branching point) at cursor position
+     */
+    private placeSelectedItem;
+    /**
+     * Update ghost preview position and overlap check during add_component mode
+     */
+    private updateAddComponentPreview;
+    /**
+     * Create ghost preview for the selected item
+     * @param selection - Component type or branching point sentinel
+     */
+    private createGhostPreview;
+    /**
+     * Dispose ghost preview and cleanup resources
+     */
+    private disposeGhostPreview;
+    /**
+     * Apply semi-transparent ghost effect to preview object
+     */
+    private applyGhostEffect;
+    /**
+     * Check if ghost preview overlaps with existing components
+     */
+    private checkGhostOverlap;
+    /**
+     * Apply red emissive to indicate invalid placement
+     */
+    private applyInvalidEffect;
+    /**
+     * Remove red emissive invalid placement effect
+     */
+    private removeInvalidEffect;
+}

package/dist/scene/static/tools/ComponentPickerWidget.d.ts

@@ -0,0 +1,89 @@
+import { ComponentType } from '../../../core/index.ts';
+import { IGroupedFactoryRegistry } from '../../shared/components/GroupedFactoryRegistry';
+/**
+ * Sentinel value representing the "Branching Point" pseudo-component entry.
+ * When selected, BuildTool creates a branching point instead of a component.
+ */
+export declare const BRANCHING_POINT_SENTINEL: "__branching_point__";
+/**
+ * Union of actual component types and the branching point sentinel.
+ */
+export type PickerSelection = ComponentType | typeof BRANCHING_POINT_SENTINEL;
+/**
+ * Persisted widget state (survives open/close cycles within a session).
+ */
+export interface ComponentPickerState {
+    selectedGroupId: string;
+    selectedItem: PickerSelection | null;
+    widgetWidth: number;
+    widgetHeight: number;
+}
+/**
+ * DOM overlay widget for selecting components from grouped registry.
+ *
+ * Features:
+ * - Group dropdown for filtering component types
+ * - Scrollable item list with selection highlight
+ * - Draggable header bar
+ * - Resizable via CSS resize
+ * - State persistence across open/close (group, selection, size)
+ */
+export declare class ComponentPickerWidget {
+    private readonly registry;
+    private container;
+    private titleEl;
+    private groupDropdown;
+    private itemList;
+    private state;
+    private readonly onSelectionChange;
+    private readonly onClose;
+    private escapeHandler;
+    private dragOffset;
+    private dragMoveHandler;
+    private dragEndHandler;
+    /**
+     * @param registry - Grouped factory registry providing groups and component types
+     * @param onSelectionChange - Called when user selects or deselects an item
+     * @param onClose - Called when user closes the widget (close button or Escape)
+     */
+    constructor(registry: IGroupedFactoryRegistry, onSelectionChange: (selection: PickerSelection | null) => void, onClose: () => void);
+    /** Whether the widget is currently open and visible */
+    get isOpen(): boolean;
+    /** The currently selected item (persists across open/close) */
+    get currentSelection(): PickerSelection | null;
+    /**
+     * Open the widget at the given screen position.
+     * If already open, repositions to the new location.
+     *
+     * @param screenPosition - Screen coordinates (typically from mouse event)
+     */
+    open(screenPosition: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * Close the widget and remove DOM.
+     * Preserves state (group, selection, size) for next open.
+     */
+    close(): void;
+    /**
+     * Full cleanup including state reset.
+     */
+    dispose(): void;
+    /**
+     * Refresh all user-visible text in place after a language change.
+     * No-op if the widget is not currently open.
+     * Preserves drag position, scroll, resize dimensions, and current selection.
+     */
+    setLanguage(_lng: string): void;
+    private createDOM;
+    private renderItemList;
+    private createItemElement;
+    private selectItem;
+    private positionContainer;
+    private startDrag;
+    private onDragMove;
+    private endDrag;
+    private registerEventListeners;
+    private removeEventListeners;
+}

package/dist/scene/static/tools/ConfigPanelWidget.d.ts

@@ -0,0 +1,107 @@
+import { UUID, Component } from '../../../core/index.ts';
+import { IFactoryRegistry } from '../../shared/components/ComponentVisualFactory';
+/**
+ * Manages lil-gui configuration panel for component config editing
+ *
+ * Responsibilities:
+ * - Panel lifecycle (open, close, dispose)
+ * - DOM container creation and positioning
+ * - lil-gui initialization and form building
+ * - Click-outside and Escape key handling
+ * - onChange event wiring to update component config
+ * - Event emission for config changes
+ */
+export declare class ConfigPanelWidget {
+    private factoryRegistry;
+    private readonly editComponentConfig;
+    private _isOpen;
+    private _currentComponentId;
+    private _currentComponent;
+    private _currentFactory;
+    private gui;
+    private container;
+    private formDataObject;
+    private clickOutsideHandler;
+    private escapeHandler;
+    /**
+     * Create a new ConfigPanelManager
+     *
+     * @param factoryRegistry - Factory registry for getting component factories
+     * @param editComponentConfig - Function to edit component config
+     * @param _camera - Three.js camera (reserved for future use)
+     * @param _domElement - Container DOM element (reserved for future use)
+     */
+    constructor(factoryRegistry: IFactoryRegistry, editComponentConfig: (componentId: UUID, newConfig: Map<string, string>) => void, _camera: unknown, _domElement: unknown);
+    /**
+     * Check if panel is currently open
+     */
+    get isOpen(): boolean;
+    /**
+     * Get the ID of the component currently being edited
+     */
+    get currentComponentId(): UUID | null;
+    /**
+     * Open the config panel for a component
+     *
+     * @param component - component to edit
+     * @param screenPosition - Screen coordinates for panel positioning
+     * @returns true if panel opened, false if component has no config
+     */
+    open(component: Component, screenPosition: {
+        x: number;
+        y: number;
+    }): boolean;
+    /**
+     * Close the config panel if open
+     */
+    close(): void;
+    /**
+     * Dispose of all resources
+     */
+    dispose(): void;
+    /**
+     * Position the container adjacent to component (right side preferred)
+     */
+    private positionContainer;
+    /**
+     * Build lil-gui from form definition
+     */
+    private buildGui;
+    /**
+     * Handle value change in the config form
+     * Maps form data back to core config and updates the component.
+     * When defaultLogicFamily or activationLogic changes, rebuilds the GUI to reflect
+     * updated disabled states and computed transitionSpan values.
+     *
+     * @param changedKey - The key of the field that changed
+     * @param _value - The new value
+     * @param component - Component being edited
+     * @param factory - Visual factory for the component
+     */
+    private onValueChange;
+    /**
+     * Resolve a form field label via i18n, falling back to a humanised form
+     * of the field key when no translation is available (e.g. "transitionSpan" →
+     * "Transition Span"). The fallback covers two cases: (a) the consumer never
+     * called registerSceTranslations, (b) the key is not yet in the locale file.
+     */
+    private _resolveFieldLabel;
+    /**
+     * Refresh the panel to display strings in the current language.
+     * No-op if the panel is not open.
+     */
+    setLanguage(_lng: string): void;
+    /**
+     * Rebuild the GUI in place, re-reading the updated component config.
+     * Used after interdependent field changes (defaultLogicFamily, activationLogic).
+     */
+    private rebuildGui;
+    /**
+     * Setup event listeners for dismissing the panel
+     */
+    private setupEventListeners;
+    /**
+     * Remove event listeners
+     */
+    private removeEventListeners;
+}