rocket-welder-sdk 1.1.36.dev14__py3-none-any.whl

rocket_welder_sdk/ui/ui_events_projection.py

@@ -0,0 +1,226 @@
+"""UI Events Projection for handling incoming events from the UI."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from contextlib import suppress
+from threading import Event as ThreadingEvent
+from typing import TYPE_CHECKING, Any, Protocol
+
+from rocket_welder_sdk.external_controls.contracts import (
+    ButtonDown,
+    ButtonUp,
+    KeyDown,
+    KeyUp,
+)
+
+if TYPE_CHECKING:
+    from esdbclient import EventStoreDBClient, RecordedEvent
+
+logger = logging.getLogger(__name__)
+
+
+class IEventQueue(Protocol):
+    """Protocol for event queue."""
+
+    def enqueue_event(self, event: Any) -> None:
+        """Add event to the queue."""
+        ...
+
+
+class UiEventsProjection:
+    """
+    Projection that subscribes to UI events stream and forwards them to the UiService.
+
+    Implements RAII pattern for resource management.
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        event_queue: IEventQueue,
+        eventstore_client: EventStoreDBClient,
+    ) -> None:
+        """
+        Initialize the UI events projection.
+
+        Args:
+            session_id: The session ID to subscribe to
+            event_queue: Queue to forward events to (typically UiService)
+            eventstore_client: EventStore client for subscription
+        """
+        self._session_id: str = session_id
+        self._event_queue: IEventQueue = event_queue
+        self._eventstore_client: EventStoreDBClient = eventstore_client
+        self._stream_name: str = f"Ui.Events-{session_id}"
+        self._subscription: Any | None = None
+        self._subscription_task: asyncio.Task[None] | None = None
+        self._cancellation_token: ThreadingEvent = ThreadingEvent()
+        self._is_running: bool = False
+
+    async def start(self) -> None:
+        """Start the subscription to UI events."""
+        if self._is_running:
+            raise RuntimeError("Projection is already running")
+
+        self._is_running = True
+        self._cancellation_token.clear()
+
+        # Start subscription task
+        self._subscription_task = asyncio.create_task(self._run_subscription())
+        logger.info(f"Started UI events projection for session {self._session_id}")
+
+    async def stop(self) -> None:
+        """Stop the subscription and clean up resources."""
+        if not self._is_running:
+            return
+
+        self._is_running = False
+        self._cancellation_token.set()
+
+        # Cancel subscription task
+        if self._subscription_task:
+            self._subscription_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await self._subscription_task
+            self._subscription_task = None
+
+        # Close subscription
+        if self._subscription:
+            try:
+                # Context manager will handle cleanup
+                pass
+            except Exception as e:
+                logger.warning(f"Error closing subscription: {e}")
+            finally:
+                self._subscription = None
+
+        logger.info(f"Stopped UI events projection for session {self._session_id}")
+
+    async def _run_subscription(self) -> None:
+        """Run the subscription loop."""
+        while self._is_running and not self._cancellation_token.is_set():
+            try:
+                # Subscribe from the beginning of the stream
+                # Using catch-up subscription to get all events
+                with self._eventstore_client.subscribe_to_stream(
+                    stream_name=self._stream_name,
+                    stream_position=None,  # Start from beginning
+                    include_caught_up=True,
+                ) as subscription:
+                    self._subscription = subscription
+                    logger.debug(f"Subscribed to stream {self._stream_name}")
+
+                    for recorded_event in subscription:
+                        if self._cancellation_token.is_set():
+                            break
+
+                        # Check if this is a caught-up event
+                        if hasattr(recorded_event, "is_caught_up") and recorded_event.is_caught_up:
+                            logger.debug(f"Caught up with stream {self._stream_name}")
+                            continue
+
+                        # Process the event
+                        await self._handle_event(recorded_event)
+
+            except asyncio.CancelledError:
+                # Task was cancelled, exit cleanly
+                break
+            except Exception as e:
+                logger.error(f"Error in subscription: {e}")
+                if self._is_running and not self._cancellation_token.is_set():
+                    # Wait before retrying
+                    await asyncio.sleep(5)
+                else:
+                    break
+
+    async def _handle_event(self, recorded_event: RecordedEvent) -> None:
+        """
+        Handle a recorded event from the stream.
+
+        Args:
+            recorded_event: The recorded event from EventStore
+        """
+        try:
+            # Parse event type and data
+            event_type: str = recorded_event.type
+            # Handle both dict and bytes (esdbclient may return bytes)
+            event_data: dict[str, Any]
+            if isinstance(recorded_event.data, bytes):
+                import json
+
+                event_data = json.loads(recorded_event.data)
+            else:
+                event_data = recorded_event.data
+
+            # Map event type to control event class
+            event_class: type[Any] | None = None
+
+            if event_type == "ButtonDown":
+                event_class = ButtonDown
+            elif event_type == "ButtonUp":
+                event_class = ButtonUp
+            elif event_type == "KeyDown":
+                event_class = KeyDown
+            elif event_type == "KeyUp":
+                event_class = KeyUp
+            else:
+                logger.debug(f"Ignoring unknown event type: {event_type}")
+                return
+
+            # Create event instance
+            if event_class:
+                # Convert from PascalCase to snake_case if needed
+                normalized_data = self._normalize_event_data(event_data)
+                event = event_class.model_validate(normalized_data)
+
+                # Enqueue event for processing
+                self._event_queue.enqueue_event(event)
+                logger.debug(f"Enqueued {event_type} for control {event.control_id}")
+
+        except Exception as e:
+            logger.error(f"Error handling event {recorded_event.id}: {e}")
+
+    def _normalize_event_data(self, data: dict[str, Any]) -> dict[str, Any]:
+        """
+        Normalize event data from PascalCase to snake_case.
+
+        Args:
+            data: Event data dictionary
+
+        Returns:
+            Normalized data dictionary
+        """
+        # Map common field names
+        field_mapping = {
+            "ControlId": "control_id",
+            "Code": "code",
+            "Direction": "direction",
+        }
+
+        normalized: dict[str, Any] = {}
+        for key, value in data.items():
+            # Use mapping if available, otherwise convert to snake_case
+            if key in field_mapping:
+                normalized[field_mapping[key]] = value
+            else:
+                # Simple PascalCase to snake_case conversion
+                snake_key = key[0].lower() + key[1:]
+                normalized[snake_key] = value
+
+        return normalized
+
+    async def __aenter__(self) -> UiEventsProjection:
+        """Async context manager entry."""
+        await self.start()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Async context manager exit - ensures cleanup."""
+        await self.stop()
+
+    @property
+    def is_running(self) -> bool:
+        """Check if the projection is running."""
+        return self._is_running

rocket_welder_sdk/ui/ui_service.py

@@ -0,0 +1,358 @@
+"""UI Service for managing controls and commands."""
+
+from __future__ import annotations
+
+from collections import UserList
+from typing import Any
+
+from py_micro_plumberd import CommandBus, EventStoreClient
+
+from rocket_welder_sdk.external_controls.contracts import (
+    ChangeControls,
+    DefineControl,
+    DeleteControls,
+)
+
+from .controls import (
+    ArrowGridControl,
+    ControlBase,
+    IconButtonControl,
+    LabelControl,
+)
+from .ui_events_projection import UiEventsProjection
+from .value_types import RegionName
+
+
+class ItemsControl(UserList[ControlBase]):
+    """Collection of controls for a region with automatic command scheduling."""
+
+    data: list[ControlBase]  # Type annotation for the data attribute
+
+    def __init__(self, ui_service: UiService, region_name: RegionName) -> None:
+        """
+        Initialize items control for a region.
+
+        Args:
+            ui_service: Parent UiService
+            region_name: Region where controls are placed
+        """
+        super().__init__()
+        self._ui_service: UiService = ui_service
+        self._region_name: RegionName = region_name
+
+    def append(self, item: ControlBase) -> None:
+        """Add control and schedule DefineControl command."""
+        if not isinstance(item, ControlBase):
+            raise TypeError("Only ControlBase instances can be added")
+
+        # Schedule DefineControl command
+        self._ui_service.schedule_define_control(item, self._region_name)
+        super().append(item)
+
+    def add(self, item: ControlBase) -> None:
+        """Add control (alias for append to match C# API)."""
+        self.append(item)
+
+    def remove(self, item: ControlBase) -> None:
+        """Remove control and schedule deletion."""
+        if item in self.data:
+            self._ui_service.schedule_delete(item.id)
+            super().remove(item)
+
+    def clear(self) -> None:
+        """Clear all controls and schedule deletions."""
+        for control in self.data:
+            self._ui_service.schedule_delete(control.id)
+        super().clear()
+
+
+class UiControlFactory:
+    """Factory for creating UI controls."""
+
+    def __init__(self, ui_service: UiService) -> None:
+        """
+        Initialize factory with UiService reference.
+
+        Args:
+            ui_service: Parent UiService
+        """
+        self._ui_service: UiService = ui_service
+
+    def define_icon_button(
+        self, control_id: str, icon: str, properties: dict[str, str] | None = None
+    ) -> IconButtonControl:
+        """
+        Create an icon button control.
+
+        Args:
+            control_id: Unique identifier
+            icon: SVG path for the icon
+            properties: Additional properties
+
+        Returns:
+            Created IconButtonControl
+        """
+        control = IconButtonControl(control_id, self._ui_service, icon, properties)
+        self._ui_service.register_control(control)
+        return control
+
+    def define_arrow_grid(
+        self, control_id: str, properties: dict[str, str] | None = None
+    ) -> ArrowGridControl:
+        """
+        Create an arrow grid control.
+
+        Args:
+            control_id: Unique identifier
+            properties: Additional properties
+
+        Returns:
+            Created ArrowGridControl
+        """
+        control = ArrowGridControl(control_id, self._ui_service, properties)
+        self._ui_service.register_control(control)
+        return control
+
+    def define_label(
+        self, control_id: str, text: str, properties: dict[str, str] | None = None
+    ) -> LabelControl:
+        """
+        Create a label control.
+
+        Args:
+            control_id: Unique identifier
+            text: Label text
+            properties: Additional properties
+
+        Returns:
+            Created LabelControl
+        """
+        control = LabelControl(control_id, self._ui_service, text, properties)
+        self._ui_service.register_control(control)
+        return control
+
+
+class UiService:
+    """Main service for managing UI controls and commands."""
+
+    @classmethod
+    def from_session_id(cls, session_id: str | Any) -> UiService:
+        """
+        Create UiService from session ID.
+
+        Args:
+            session_id: Session ID (string or UUID)
+
+        Returns:
+            New UiService instance
+        """
+        # Handle UUID or string
+        session_str = str(session_id) if not isinstance(session_id, str) else session_id
+        return cls(session_str)
+
+    def __init__(self, session_id: str) -> None:
+        """
+        Initialize UiService with session ID.
+
+        Args:
+            session_id: UI session ID for command routing
+        """
+        self.session_id: str = session_id
+        self.command_bus: CommandBus | None = None
+        self.factory: UiControlFactory = UiControlFactory(self)
+
+        # Control tracking
+        self._index: dict[str, ControlBase] = {}
+
+        # Scheduled operations
+        self._scheduled_definitions: list[tuple[ControlBase, RegionName]] = []
+        self._scheduled_deletions: list[str] = []
+
+        # Initialize regions - include all standard and preview regions
+        self._regions: dict[RegionName, ItemsControl] = {
+            RegionName.TOP: ItemsControl(self, RegionName.TOP),
+            RegionName.TOP_LEFT: ItemsControl(self, RegionName.TOP_LEFT),
+            RegionName.TOP_RIGHT: ItemsControl(self, RegionName.TOP_RIGHT),
+            RegionName.BOTTOM: ItemsControl(self, RegionName.BOTTOM),
+            RegionName.BOTTOM_LEFT: ItemsControl(self, RegionName.BOTTOM_LEFT),
+            RegionName.BOTTOM_RIGHT: ItemsControl(self, RegionName.BOTTOM_RIGHT),
+            # Preview regions for compatibility
+            RegionName.PREVIEW_TOP: ItemsControl(self, RegionName.PREVIEW_TOP),
+            RegionName.PREVIEW_TOP_LEFT: ItemsControl(self, RegionName.PREVIEW_TOP_LEFT),
+            RegionName.PREVIEW_TOP_RIGHT: ItemsControl(self, RegionName.PREVIEW_TOP_RIGHT),
+            RegionName.PREVIEW_BOTTOM: ItemsControl(self, RegionName.PREVIEW_BOTTOM),
+            RegionName.PREVIEW_BOTTOM_LEFT: ItemsControl(self, RegionName.PREVIEW_BOTTOM_LEFT),
+            RegionName.PREVIEW_BOTTOM_RIGHT: ItemsControl(self, RegionName.PREVIEW_BOTTOM_RIGHT),
+            RegionName.PREVIEW_BOTTOM_CENTER: ItemsControl(self, RegionName.PREVIEW_BOTTOM_CENTER),
+        }
+
+        # Event queue
+        self._event_queue: list[Any] = []
+
+        # Event projection
+        self._events_projection: UiEventsProjection | None = None
+
+    def __getitem__(self, region: RegionName) -> ItemsControl:
+        """Get controls for a region."""
+        return self._regions[region]
+
+    async def initialize(self, eventstore_client: EventStoreClient) -> None:
+        """
+        Initialize with EventStore client and start event projection.
+
+        Args:
+            eventstore_client: EventStore client for commands and events
+        """
+        self.command_bus = CommandBus(eventstore_client)
+
+        # Start the events projection to receive UI events
+        self._events_projection = UiEventsProjection(
+            session_id=self.session_id,
+            event_queue=self,  # UiService implements the IEventQueue protocol
+            eventstore_client=eventstore_client._client,  # Use the underlying esdbclient
+        )
+        await self._events_projection.start()
+
+    async def dispose(self) -> None:
+        """Dispose the service and clean up resources."""
+        # Stop the events projection
+        if self._events_projection:
+            await self._events_projection.stop()
+            self._events_projection = None
+
+        # Clear all controls
+        for control_id in list(self._index.keys()):
+            control = self._index[control_id]
+            control.dispose()
+
+        # Clear regions
+        for region in self._regions.values():
+            region.clear()
+
+    def register_control(self, control: ControlBase) -> None:
+        """
+        Register a control in the index.
+
+        Args:
+            control: Control to register
+        """
+        self._index[control.id] = control
+
+    def schedule_define_control(self, control: ControlBase, region: RegionName) -> None:
+        """
+        Schedule a DefineControl command.
+
+        Args:
+            control: Control to define
+            region: Region where control is placed
+        """
+        self._scheduled_definitions.append((control, region))
+
+    def schedule_delete(self, control_id: str) -> None:
+        """
+        Schedule a control deletion.
+
+        Args:
+            control_id: ID of control to delete
+        """
+        self._scheduled_deletions.append(control_id)
+
+    def enqueue_event(self, event: Any) -> None:
+        """
+        Enqueue an event for processing.
+
+        Args:
+            event: Event to enqueue
+        """
+        self._event_queue.append(event)
+
+    async def do(self) -> None:
+        """Process all scheduled operations and events."""
+        # Dispatch events
+        self._dispatch_events()
+
+        # Process scheduled definitions
+        await self._process_scheduled_definitions()
+
+        # Process scheduled deletions
+        await self._process_scheduled_deletions()
+
+        # Send property updates
+        await self._send_property_updates()
+
+    def _dispatch_events(self) -> None:
+        """Dispatch queued events to controls."""
+        for event in self._event_queue:
+            if hasattr(event, "control_id"):
+                control_id: str = event.control_id
+                control = self._index.get(control_id)
+                if control:
+                    control.handle_event(event)
+        self._event_queue.clear()
+
+    async def _process_scheduled_definitions(self) -> None:
+        """Process scheduled DefineControl commands."""
+        for control, region in self._scheduled_definitions:
+            # Add to index when actually defining
+            self._index[control.id] = control
+
+            command = DefineControl(
+                control_id=control.id,
+                type=control.control_type,
+                properties=control.properties,
+                region_name=region.value,
+            )
+
+            if self.command_bus:
+                await self.command_bus.send_async(recipient_id=self.session_id, command=command)
+
+            control.commit_changes()
+
+        self._scheduled_definitions.clear()
+
+    async def _process_scheduled_deletions(self) -> None:
+        """Process scheduled DeleteControls commands."""
+        if not self._scheduled_deletions:
+            return
+
+        # Batch delete command
+        command = DeleteControls(control_ids=self._scheduled_deletions.copy())
+
+        if self.command_bus:
+            await self.command_bus.send_async(recipient_id=self.session_id, command=command)
+
+        # Remove from index and regions
+        for control_id in self._scheduled_deletions:
+            control = self._index.pop(control_id, None)
+            if control:
+                for region in self._regions.values():
+                    if control in region:
+                        region.data.remove(control)
+
+        self._scheduled_deletions.clear()
+
+    async def _send_property_updates(self) -> None:
+        """Send ChangeControls command for dirty controls."""
+        updates: dict[str, dict[str, str]] = {}
+
+        for region in self._regions.values():
+            for control in region:
+                if control.is_dirty:
+                    updates[control.id] = control.changed
+
+        if updates and self.command_bus:
+            command = ChangeControls(updates=updates)
+
+            await self.command_bus.send_async(recipient_id=self.session_id, command=command)
+
+            # Commit changes
+            for control_id in updates:
+                self._index[control_id].commit_changes()
+
+    async def __aenter__(self) -> UiService:
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Async context manager exit - ensures cleanup."""
+        await self.dispose()

rocket_welder_sdk/ui/value_types.py

@@ -0,0 +1,72 @@
+"""Value types for UI controls matching C# value types."""
+
+from enum import Enum
+
+
+class ControlType(str, Enum):
+    """Control types matching C# ControlType enum."""
+
+    ICON_BUTTON = "IconButton"
+    ARROW_GRID = "ArrowGrid"
+    LABEL = "Label"
+
+
+class RegionName(str, Enum):
+    """Region names for control placement."""
+
+    TOP = "Top"
+    TOP_LEFT = "TopLeft"
+    TOP_RIGHT = "TopRight"
+    BOTTOM = "Bottom"
+    BOTTOM_LEFT = "BottomLeft"
+    BOTTOM_RIGHT = "BottomRight"
+
+    # Legacy names for compatibility
+    PREVIEW_TOP = "preview-top"
+    PREVIEW_TOP_LEFT = "preview-top-left"
+    PREVIEW_TOP_RIGHT = "preview-top-right"
+    PREVIEW_BOTTOM = "preview-bottom"
+    PREVIEW_BOTTOM_LEFT = "preview-bottom-left"
+    PREVIEW_BOTTOM_RIGHT = "preview-bottom-right"
+    PREVIEW_BOTTOM_CENTER = "preview-bottom-center"
+
+
+class Color(str, Enum):
+    """Color values for controls."""
+
+    PRIMARY = "Primary"
+    SECONDARY = "Secondary"
+    SUCCESS = "Success"
+    INFO = "Info"
+    WARNING = "Warning"
+    ERROR = "Error"
+    TEXT_PRIMARY = "TextPrimary"
+    TEXT_SECONDARY = "TextSecondary"
+    DEFAULT = "Default"
+
+
+class Size(str, Enum):
+    """Size values for controls."""
+
+    EXTRA_SMALL = "ExtraSmall"
+    SMALL = "Small"
+    MEDIUM = "Medium"
+    LARGE = "Large"
+    EXTRA_LARGE = "ExtraLarge"
+
+
+class Typography(str, Enum):
+    """Typography values for text controls."""
+
+    H1 = "h1"
+    H2 = "h2"
+    H3 = "h3"
+    H4 = "h4"
+    H5 = "h5"
+    H6 = "h6"
+    SUBTITLE1 = "subtitle1"
+    SUBTITLE2 = "subtitle2"
+    BODY1 = "body1"
+    BODY2 = "body2"
+    CAPTION = "caption"
+    OVERLINE = "overline"