GUIAdapter

GUI/Adapters~GUIAdapter. GUIAdapter

new GUIAdapter(_controlsnullable, canvasnon-null, circuitServicenon-null, elementRegistrynon-null, rendererFactorynon-null, guiCommandRegistrynon-null)

Source:
Parameters:
Name Type Attributes Description
_controls HTMLElement <nullable>

Deprecated. Kept for signature compatibility; not used.
canvas HTMLCanvasElement

Canvas for circuit rendering.
circuitService CircuitService

Core domain service (aggregate orchestration, emits "update").
elementRegistry ElementRegistry

Registry of circuit components (DI).
rendererFactory RendererFactory

Factory for creating renderers (DI).
guiCommandRegistry GUICommandRegistry

Registry for GUI commands (DI).

Methods

bindImageLoadEvents()

Bind renderer image load events to trigger re-renders when images finish loading.

Description:

  • Bind renderer image load events to trigger re-renders when images finish loading.

Source:

bindMenu()

Bind config-driven menubar events to action handling.

Description:

  • Bind config-driven menubar events to action handling. The MenuBar emits: CustomEvent('ui:action', { detail: { id } }).

Source:

bindShortcuts(keymapnon-null)

Bind global keyboard shortcuts to the same action ids from config.

Description:

  • Bind global keyboard shortcuts to the same action ids from config.

Source:
Parameters:
Name Type Description
keymap Object.<string, string>

Map of "Ctrl+X" → "action.id"

bindWheelZoom()

Convert Ctrl+wheel into renderer zoom steps (declarative equivalent).

Description:

  • Convert Ctrl+wheel into renderer zoom steps (declarative equivalent). Leaves normal scrolling alone if Ctrl is not pressed.

Source:

dispose()

Unhook global listeners (useful for hot-reload/tests).

Description:

  • Unhook global listeners (useful for hot-reload/tests).

Source:

findElementAt(worldX, worldY) → (nullable) {Object}

🎯 Element Selection Logic - Smart element detection at coordinates.

Description:

  • 🎯 Element Selection Logic - Smart element detection at coordinates.

    Implements intelligent selection priorities:

    1. Node Proximity: Elements with nodes near click point rank higher
    2. Type Priority: Non-wire elements preferred over wires
    3. Hit Testing: Uses element-specific intersection algorithms

    This method is crucial for user experience - determines which element responds to clicks when multiple elements overlap.

    Extension Point: Override for custom selection behavior.

Source:
Example
// Custom selection logic
const element = adapter.findElementAt(mouseX, mouseY);
if (element?.type === 'myCustomType') {
  // Handle custom element interaction
}
Parameters:
Name Type Description
worldX number

World X coordinate
worldY number

World Y coordinate
Returns:

Best matching element or null

Type
Object

getTransformedMousePosition(eventnon-null) → {Object}

📐 Coordinate Transformation - Converts screen to world coordinates.

Description:

  • 📐 Coordinate Transformation - Converts screen to world coordinates.

    Essential for mouse interactions on the canvas. Accounts for:

    • Canvas position in viewport
    • Renderer pan offset
    • Renderer zoom scale

    Use this for all mouse position calculations in extensions.

Source:
Example
canvas.addEventListener('click', (event) => {
  const { offsetX, offsetY } = adapter.getTransformedMousePosition(event);
  // Use world coordinates for element placement, hit testing, etc.
});
Parameters:
Name Type Description
event MouseEvent

Mouse event from canvas
Returns:

World coordinates

Type
Object

handleAction(id)

🎯 Primary Action Handler - Main extension point for custom actions.

Description:

  • 🎯 Primary Action Handler - Main extension point for custom actions.

    Routes semantic action IDs from configuration to appropriate handlers. This is where developers can intercept and customize user interactions.

    Action Flow:

    1. UI emits semantic action ID (from menu.config.yaml)
    2. GUIAdapter maps ID to action specification
    3. Executes appropriate command, renderer operation, or history action

    Extension Pattern: Add new actions in menu.config.yaml, register commands in GUICommandRegistry.

Source:
Examples
// Programmatic action triggering
guiAdapter.handleAction('insert.resistor');
guiAdapter.handleAction('edit.undo');
// Custom action handling (extend via configuration)
// In menu.config.yaml:
// actions:
//   'custom.optimize': { kind: 'command', name: 'optimizeCircuit' }
guiAdapter.handleAction('custom.optimize');
Parameters:
Name Type Description
id string

Action identifier (e.g., "edit.undo", "insert.resistor")

handleElementDoubleClick(element, isNewlyPlaced)

Handles double-click on circuit elements to open property panel.

Description:

  • Handles double-click on circuit elements to open property panel.

Source:
Parameters:
Name Type Default Description
element Object

The clicked circuit element
isNewlyPlaced boolean false

Whether this element was just placed (true) or is being edited (false)

hasStateChanged(before, after) → {boolean}

Shallow state delta check for snapshotting (undo batching).

Description:

  • Shallow state delta check for snapshotting (undo batching).

Source:
Parameters:
Name Type Description
before string | Object

JSON string or object
after string | Object

JSON string or object
Returns:
Type
boolean

initialize()

🚀 Initialization Method - Sets up the complete adapter with all bindings.

Description:

  • 🚀 Initialization Method - Sets up the complete adapter with all bindings.

    Establishes the hexagonal architecture connections:

    • Menu system → action handling
    • Keyboard shortcuts → action routing
    • Mouse/touch interactions → command execution
    • Event system → automatic UI updates

    Extension Points Initialized:

    • Menu action bindings (config-driven)
    • Keyboard shortcut mapping
    • Canvas interaction handlers
    • Property panel integration
    • Domain event listeners for UI updates

    Call this after creating the adapter to activate all functionality.

Source:
Example
const adapter = new GUIAdapter(canvas, circuitService, elementRegistry,
                               rendererFactory, commandRegistry);
adapter.initialize(); // Activates all interactions

isInsideElement(x, y, elementnon-null) → {boolean}

Hit-test for a line-like element with an "aura".

Description:

  • Hit-test for a line-like element with an "aura".

Source:
Parameters:
Name Type Description
x number
y number
element Object
Returns:
Type
boolean

setupCanvasInteractions()

Sets up mouse events for interaction on the canvas: pan (MMB), drag, draw, placement.

Description:

  • Sets up mouse events for interaction on the canvas: pan (MMB), drag, draw, placement. Note: Ctrl+wheel zoom is handled by bindWheelZoom(); regular wheel is left to the page.

Source:

setupPropertyPanel()

Sets up property panel integration with double-click handling.

Description:

  • Sets up property panel integration with double-click handling.

Source: