pyview-web 0.3.0__py3-none-any.whl → 0.8.0a2__py3-none-any.whl

pyview/components/base.py

@@ -0,0 +1,212 @@
+"""
+Base classes for PyView LiveComponents.
+
+LiveComponents are stateful, reusable UI components that can handle their own
+events and maintain isolated state. They are inspired by Phoenix LiveComponents.
+
+Key concepts:
+- LiveComponent: Base class defining component behavior (lifecycle, events, template)
+- ComponentMeta: Metadata passed to template(), includes `myself` (CID) for event targeting
+- ComponentSocket: Handle passed to lifecycle methods for state access
+
+CID (Component ID) is stored externally in ComponentsManager, not on the component
+instance. This keeps components clean and testable.
+"""
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Generic, Optional, TypeVar
+
+if TYPE_CHECKING:
+    from string.templatelib import Template  # type: ignore[import-not-found]
+
+    from pyview.meta import PyViewMeta
+
+    # Avoid circular import - manager imports this module
+    from .manager import ComponentsManager
+
+T = TypeVar("T")
+
+
+@dataclass
+class ComponentMeta:
+    """
+    Metadata passed to component's template() method.
+
+    Contains the component's CID (Component ID) which is used for event targeting
+    via phx-target={meta.myself}, and any slots passed from the parent.
+
+    Attributes:
+        cid: The component's unique identifier (assigned by ComponentsManager)
+        parent_meta: The parent LiveView's PyViewMeta
+        slots: Dictionary of slot content passed from parent template
+    """
+
+    cid: int
+    parent_meta: "PyViewMeta"
+    slots: "dict[str, Template]" = field(default_factory=dict)
+
+    @property
+    def myself(self) -> int:
+        """
+        Returns the CID for use in phx-target.
+
+        This is the Python equivalent of Phoenix's @myself.
+        Use it in templates: phx-target="{meta.myself}"
+        """
+        return self.cid
+
+
+@dataclass
+class ComponentSocket(Generic[T]):
+    """
+    Socket passed to component lifecycle methods.
+
+    This is an ephemeral handle created for each lifecycle call (mount, update,
+    handle_event). The context is the persistent state, stored externally in
+    ComponentsManager.
+
+    Attributes:
+        context: The component's current state (read/write)
+        cid: The component's unique identifier
+        manager: Reference to the ComponentsManager for advanced operations
+    """
+
+    context: T
+    cid: int
+    manager: "ComponentsManager"
+
+    @property
+    def myself(self) -> int:
+        """Returns the CID for use in templates/events."""
+        return self.cid
+
+    async def send_parent(self, event: str, payload: Optional[dict[str, Any]] = None) -> None:
+        """
+        Send an event to the parent LiveView.
+
+        This allows components to communicate upward to their parent.
+        The parent's handle_event will be called with this event.
+
+        Args:
+            event: Event name
+            payload: Optional event payload
+        """
+        if payload is None:
+            payload = {}
+        await self.manager.send_to_parent(event, payload)
+
+
+class LiveComponent(Generic[T]):
+    """
+    Base class for stateful live components.
+
+    LiveComponents have their own state and can handle events targeted at them
+    via phx-target={meta.myself}. They are identified by a unique CID assigned
+    by the ComponentsManager.
+
+    Lifecycle:
+        1. mount(socket, assigns) - Called once when component first appears
+        2. update(socket, assigns) - Called when parent passes new assigns
+        3. template(assigns, meta) - Called to render the component
+        4. handle_event(event, payload, socket) - Called for targeted events
+
+    Error Handling:
+        Errors in lifecycle methods (mount, update, handle_event) are logged with
+        full context (component class name, CID, method) and then re-raised. This
+        matches Phoenix LiveView behavior where component errors crash the parent
+        LiveView process. The client-side JavaScript will automatically attempt
+        to reconnect and remount the view.
+
+        This "let it crash" approach ensures:
+        - Errors are visible during development
+        - No partial/inconsistent UI state
+        - Automatic recovery via reconnection
+
+    Example:
+        class Counter(LiveComponent[CounterContext]):
+            async def mount(self, socket: ComponentSocket[CounterContext], assigns: dict):
+                # Initialize state from parent assigns
+                socket.context = {
+                    "count": assigns.get("initial", 0),
+                    "label": assigns.get("label", "Counter")
+                }
+
+            async def update(self, socket: ComponentSocket[CounterContext], assigns: dict):
+                # React to changed assigns from parent (e.g., label updates)
+                if "label" in assigns:
+                    socket.context["label"] = assigns["label"]
+
+            def template(self, assigns: CounterContext, meta: ComponentMeta):
+                return t'''
+                    <div>
+                        <span>{assigns["count"]}</span>
+                        <button phx-click="increment" phx-target="{meta.myself}">+</button>
+                    </div>
+                '''
+
+            async def handle_event(self, event: str, payload: dict, socket: ComponentSocket):
+                if event == "increment":
+                    socket.context["count"] += 1
+    """
+
+    async def mount(self, socket: ComponentSocket[T], assigns: dict[str, Any]) -> None:
+        """
+        Called once when the component is first added to the page.
+
+        Use this to initialize the component's state (socket.context) from
+        the initial assigns passed by the parent.
+
+        Args:
+            socket: ComponentSocket for state access
+            assigns: Initial assigns from parent (e.g., label, initial values)
+        """
+        pass
+
+    async def update(self, socket: ComponentSocket[T], assigns: dict[str, Any]) -> None:
+        """
+        Called after mount() and on subsequent renders with new assigns.
+
+        This is called:
+        1. Immediately after mount() with the initial assigns
+        2. On re-renders when the parent passes new assigns via live_component()
+
+        Override to handle assigns that should update component state.
+        The default is a no-op - components explicitly decide what affects their state.
+
+        Args:
+            socket: ComponentSocket for state access
+            assigns: Assigns passed from parent via live_component()
+        """
+        pass
+
+    def template(self, assigns: T, meta: ComponentMeta) -> Any:
+        """
+        Render the component's template.
+
+        Must return a Template (t-string). The meta parameter provides
+        access to `myself` for event targeting.
+
+        Args:
+            assigns: The component's current context/state
+            meta: ComponentMeta with cid/myself for event targeting
+
+        Returns:
+            A t-string Template
+        """
+        raise NotImplementedError("LiveComponent subclasses must implement template()")
+
+    async def handle_event(
+        self, event: str, payload: dict[str, Any], socket: ComponentSocket[T]
+    ) -> None:
+        """
+        Handle events targeted at this component.
+
+        Events are targeted via phx-target="{meta.myself}" in templates.
+        Without phx-target, events go to the parent LiveView instead.
+
+        Args:
+            event: Event name (e.g., "increment", "submit")
+            payload: Event payload/value
+            socket: ComponentSocket for state access
+        """
+        pass

pyview/components/lifecycle.py

@@ -0,0 +1,85 @@
+"""
+Helper for running component lifecycle with nested component discovery.
+
+This module handles nested component discovery (e.g., components inside slots),
+which requires iterating lifecycle + template rendering until no new components
+are discovered. Used by both HTTP (unconnected) and WebSocket (connected) flows.
+"""
+
+import sys
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pyview.components import SocketWithComponents
+    from pyview.meta import PyViewMeta
+
+MAX_COMPONENT_ITERATIONS = 10
+
+
+async def run_nested_component_lifecycle(
+    socket: "SocketWithComponents",
+    meta: "PyViewMeta",
+    max_iterations: int = MAX_COMPONENT_ITERATIONS,
+) -> dict[int, dict[str, Any]]:
+    """
+    Run component lifecycle, discovering nested components and returning rendered trees.
+
+    On Python 3.14+, this iterates to discover components nested inside
+    other components' templates. On earlier versions, it just runs the
+    initial lifecycle (no t-string support means no nested components).
+
+    Args:
+        socket: Socket with components manager
+        meta: PyViewMeta for component rendering
+        max_iterations: Maximum iteration limit to catch circular dependencies
+
+    Returns:
+        Dictionary mapping CID to rendered wire format tree
+    """
+    await socket.components.run_pending_lifecycle()
+
+    # Nested component discovery only works with t-strings (Python 3.14+)
+    if sys.version_info < (3, 14):
+        return {}
+
+    # Import t-string support (guarded by version check above)
+    from string.templatelib import Template
+
+    from pyview.template.live_view_template import LiveViewTemplate
+
+    # Track which CIDs we've already discovered nested components for
+    discovered_cids: set[int] = set()
+    rendered_trees: dict[int, dict[str, Any]] = {}
+    iterations = 0
+
+    while True:
+        # Only process CIDs that were seen (registered) in the current render cycle.
+        # This prevents rendering stale components from previous renders, which could
+        # resurrect their nested children and leave orphaned components in the response.
+        seen_cids = socket.components.get_seen_cids()
+        new_cids = seen_cids - discovered_cids
+
+        # Exit if no new components and no pending lifecycle
+        if not new_cids and not socket.components.has_pending_lifecycle():
+            break
+
+        # Render new component templates to discover nested components
+        for cid in new_cids:
+            discovered_cids.add(cid)
+            template: Any = socket.components.render_component(cid, meta)
+            if isinstance(template, Template):
+                tree = LiveViewTemplate.process(template, socket=socket)
+                tree["r"] = 1  # ROOT flag for Phoenix.js
+                rendered_trees[cid] = tree
+
+        # If nested components were discovered, run their lifecycle
+        if socket.components.has_pending_lifecycle():
+            if iterations >= max_iterations:
+                raise RuntimeError(
+                    f"Component lifecycle exceeded {max_iterations} iterations. "
+                    "Check for circular component dependencies."
+                )
+            await socket.components.run_pending_lifecycle()
+            iterations += 1
+
+    return rendered_trees

pyview/components/manager.py

@@ -0,0 +1,366 @@
+"""
+ComponentsManager - Manages component lifecycle and state.
+
+The manager is attached to a ConnectedLiveViewSocket and handles:
+- Component registration and CID assignment
+- External storage of component state (contexts)
+- Lifecycle orchestration (mount, update)
+- Event routing to specific components
+- Component rendering
+
+Key design: Components are identified by (module, id) tuple.
+Same module + id = same component instance across re-renders.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Protocol
+
+from .base import ComponentMeta, ComponentSocket, LiveComponent
+from .slots import Slots
+
+if TYPE_CHECKING:
+    from pyview.meta import PyViewMeta
+
+logger = logging.getLogger(__name__)
+
+
+class LiveViewProtocol(Protocol):
+    """Protocol for LiveView's handle_event method."""
+
+    async def handle_event(self, event: str, payload: dict[str, Any], socket: Any) -> None: ...
+
+
+class ParentSocketProtocol(Protocol):
+    """Protocol defining what ComponentsManager needs from its parent socket.
+
+    ComponentsManager only uses parent_socket.liveview.handle_event() for
+    sending events from components to their parent LiveView.
+    """
+
+    @property
+    def liveview(self) -> LiveViewProtocol: ...
+
+
+class ComponentsManager:
+    """
+    Manages LiveComponent instances, state, and lifecycle.
+
+    Components are stored by CID (Component ID), an integer assigned
+    on first registration. The (component_class, component_id) tuple
+    maps to a CID, allowing components to persist across re-renders.
+
+    Attributes:
+        parent_socket: The parent LiveView's socket
+        _components: CID -> LiveComponent instance mapping
+        _contexts: CID -> component context (state) mapping
+        _by_key: (class, id) -> CID mapping for identity
+        _pending_mounts: CIDs that need mount() called
+        _pending_updates: CIDs that need update() called with new assigns
+    """
+
+    def __init__(self, parent_socket: ParentSocketProtocol):
+        self.parent_socket = parent_socket
+        self._components: dict[int, LiveComponent] = {}
+        self._contexts: dict[int, Any] = {}
+        self._slots: dict[int, Slots] = {}  # Slot content keyed by CID
+        self._by_key: dict[tuple[type, str], int] = {}
+        self._pending_mounts: list[tuple[int, dict[str, Any]]] = []
+        self._pending_updates: list[tuple[int, dict[str, Any]]] = []
+        self._next_cid = 1
+        self._seen_this_render: set[int] = set()  # Track CIDs seen during current render
+
+    def register(
+        self, component_class: type[LiveComponent], component_id: str, assigns: dict[str, Any]
+    ) -> int:
+        """
+        Register a component, returning its CID.
+
+        If this (class, id) combination already exists, returns the existing CID
+        and queues an update. Otherwise, creates a new component and queues mount.
+
+        Args:
+            component_class: The LiveComponent subclass
+            component_id: User-provided unique ID for this component instance
+            assigns: Props/assigns passed from parent template
+
+        Returns:
+            The component's CID (integer)
+        """
+        key = (component_class, component_id)
+
+        # Extract slots from assigns (if present) without mutating caller's dict
+        component_slots = assigns.get("slots", {})
+        if "slots" in assigns:
+            assigns = {k: v for k, v in assigns.items() if k != "slots"}
+
+        if key in self._by_key:
+            # Existing component - queue update with new assigns
+            cid = self._by_key[key]
+            self._slots[cid] = component_slots  # Update slots
+            self._pending_updates.append((cid, assigns))
+            self._seen_this_render.add(cid)
+            logger.debug(
+                f"Component {component_class.__name__}:{component_id} (cid={cid}) queued for update"
+            )
+            return cid
+
+        # New component - assign CID and create instance
+        cid = self._next_cid
+        self._next_cid += 1
+
+        component = component_class()
+        self._components[cid] = component
+        self._contexts[cid] = {}  # Empty initial context
+        self._slots[cid] = component_slots  # Store slots
+        self._by_key[key] = cid
+
+        # Queue mount with initial assigns
+        self._pending_mounts.append((cid, assigns))
+        self._seen_this_render.add(cid)
+        logger.debug(
+            f"Component {component_class.__name__}:{component_id} (cid={cid}) registered and queued for mount"
+        )
+
+        return cid
+
+    def get_component(self, cid: int) -> tuple[LiveComponent, Any] | None:
+        """
+        Get a component and its context by CID.
+
+        Args:
+            cid: Component ID
+
+        Returns:
+            Tuple of (component, context) or None if not found
+        """
+        if cid not in self._components:
+            return None
+        return (self._components[cid], self._contexts[cid])
+
+    def get_context(self, cid: int) -> Any:
+        """Get a component's context by CID."""
+        return self._contexts.get(cid)
+
+    def set_context(self, cid: int, context: Any) -> None:
+        """Set a component's context by CID."""
+        self._contexts[cid] = context
+
+    async def run_pending_lifecycle(self) -> None:
+        """
+        Execute pending mount and update calls.
+
+        Should be called after template rendering to process any
+        components that were registered during the render.
+        """
+        # Process mounts first
+        while self._pending_mounts:
+            cid, assigns = self._pending_mounts.pop(0)
+            await self._run_mount(cid, assigns)
+
+        # Then process updates
+        while self._pending_updates:
+            cid, assigns = self._pending_updates.pop(0)
+            await self._run_update(cid, assigns)
+
+    async def _run_mount(self, cid: int, assigns: dict[str, Any]) -> None:
+        """Run mount lifecycle for a component."""
+        if cid not in self._components:
+            logger.warning(f"Cannot mount component cid={cid}: not found")
+            return
+
+        component = self._components[cid]
+        socket = self._create_socket(cid)
+
+        component_name = component.__class__.__name__
+        try:
+            # Pass assigns to mount so component can initialize from parent props
+            await component.mount(socket, assigns)
+            # Persist context changes
+            self._contexts[cid] = socket.context
+            logger.debug(f"Component {component_name} (cid={cid}) mounted successfully")
+        except Exception as e:
+            logger.error(f"Error in {component_name}.mount() (cid={cid}): {e}", exc_info=True)
+            raise
+
+        # After mount, run update with initial assigns (Phoenix pattern)
+        await self._run_update(cid, assigns)
+
+    async def _run_update(self, cid: int, assigns: dict[str, Any]) -> None:
+        """Run update lifecycle for a component."""
+        if cid not in self._components:
+            logger.warning(f"Cannot update component cid={cid}: not found")
+            return
+
+        component = self._components[cid]
+        socket = self._create_socket(cid)
+
+        component_name = component.__class__.__name__
+        try:
+            await component.update(socket, assigns)
+            # Persist context changes
+            self._contexts[cid] = socket.context
+            logger.debug(
+                f"Component {component_name} (cid={cid}) updated with assigns: {list(assigns.keys())}"
+            )
+        except Exception as e:
+            logger.error(f"Error in {component_name}.update() (cid={cid}): {e}", exc_info=True)
+            raise
+
+    async def handle_event(self, cid: int, event: str, payload: dict[str, Any]) -> None:
+        """
+        Route an event to a specific component.
+
+        Called when an event has phx-target pointing to this component's CID.
+
+        Args:
+            cid: Target component's CID
+            event: Event name
+            payload: Event payload
+        """
+        if cid not in self._components:
+            logger.warning(f"Event '{event}' targeted non-existent component cid={cid}")
+            return
+
+        component = self._components[cid]
+        socket = self._create_socket(cid)
+
+        component_name = component.__class__.__name__
+        try:
+            await component.handle_event(event, payload, socket)
+            # Persist context changes
+            self._contexts[cid] = socket.context
+            logger.debug(f"Component {component_name} (cid={cid}) handled event '{event}'")
+        except Exception as e:
+            logger.error(
+                f"Error in {component_name}.handle_event('{event}') (cid={cid}): {e}", exc_info=True
+            )
+            raise
+
+    def render_component(self, cid: int, parent_meta: PyViewMeta) -> Any:
+        """
+        Render a component and return its template result.
+
+        Args:
+            cid: Component's CID
+            parent_meta: Parent LiveView's meta
+
+        Returns:
+            The result of component.template()
+        """
+        if cid not in self._components:
+            logger.warning(f"Cannot render component cid={cid}: not found")
+            return None
+
+        component = self._components[cid]
+        context = self._contexts[cid]
+        component_slots = self._slots.get(cid, {})
+        meta = ComponentMeta(cid=cid, parent_meta=parent_meta, slots=component_slots)
+
+        return component.template(context, meta)
+
+    async def send_to_parent(self, event: str, payload: dict[str, Any]) -> None:
+        """
+        Send an event to the parent LiveView.
+
+        Called by ComponentSocket.send_parent().
+
+        Args:
+            event: Event name
+            payload: Event payload
+        """
+        await self.parent_socket.liveview.handle_event(event, payload, self.parent_socket)
+
+    def _create_socket(self, cid: int) -> ComponentSocket:
+        """Create a ComponentSocket for lifecycle/event calls."""
+        return ComponentSocket(
+            context=self._contexts.get(cid, {}),
+            cid=cid,
+            manager=self,
+        )
+
+    def unregister(self, cid: int) -> None:
+        """
+        Remove a component from the manager.
+
+        Called when a component is removed from the DOM.
+
+        Args:
+            cid: Component's CID
+        """
+        if cid in self._components:
+            del self._components[cid]
+        if cid in self._contexts:
+            del self._contexts[cid]
+        if cid in self._slots:
+            del self._slots[cid]
+
+        # Remove from key mapping
+        key_to_remove = None
+        for key, stored_cid in self._by_key.items():
+            if stored_cid == cid:
+                key_to_remove = key
+                break
+        if key_to_remove:
+            del self._by_key[key_to_remove]
+
+        logger.debug(f"Component cid={cid} unregistered")
+
+    def clear(self) -> None:
+        """Clear all components. Called on socket close."""
+        self._components.clear()
+        self._contexts.clear()
+        self._slots.clear()
+        self._by_key.clear()
+        self._pending_mounts.clear()
+        self._pending_updates.clear()
+        self._seen_this_render.clear()
+        logger.debug("ComponentsManager cleared")
+
+    def begin_render(self) -> None:
+        """
+        Start a new render cycle.
+
+        Clears the set of seen components. Call this before rendering
+        the parent LiveView template.
+        """
+        self._seen_this_render.clear()
+
+    def prune_stale_components(self) -> list[int]:
+        """
+        Remove components that weren't seen during this render cycle.
+
+        Components not referenced in the current render are considered
+        removed from the DOM and should be cleaned up.
+
+        Returns:
+            List of CIDs that were pruned
+        """
+        all_cids = set(self._components.keys())
+        stale_cids = all_cids - self._seen_this_render
+
+        for cid in stale_cids:
+            self.unregister(cid)
+
+        if stale_cids:
+            logger.debug(f"Pruned {len(stale_cids)} stale components: {stale_cids}")
+
+        return list(stale_cids)
+
+    @property
+    def component_count(self) -> int:
+        """Number of registered components."""
+        return len(self._components)
+
+    def get_all_cids(self) -> list[int]:
+        """Get all registered CIDs."""
+        return list(self._components.keys())
+
+    def get_seen_cids(self) -> set[int]:
+        """Get CIDs that were seen (registered) during the current render cycle."""
+        return self._seen_this_render.copy()
+
+    def has_pending_lifecycle(self) -> bool:
+        """Check if there are components waiting for mount/update."""
+        return bool(self._pending_mounts) or bool(self._pending_updates)

pyview/components/renderer.py

@@ -0,0 +1,14 @@
+"""
+Component rendering utilities.
+
+This module requires Python 3.14+ for t-string support.
+"""
+
+from typing import Any
+
+from pyview.template.live_view_template import LiveViewTemplate
+
+
+def render_component_tree(template: Any, socket: Any) -> dict[str, Any]:
+    """Process a component template into Phoenix wire format."""
+    return LiveViewTemplate.process(template, socket=socket)