pulse-framework 0.1.53__py3-none-any.whl → 0.1.54__py3-none-any.whl

pulse/js/obj.py

@@ -0,0 +1,79 @@
+"""
+JavaScript object literal creation.
+
+Usage:
+    from pulse.js import obj
+
+    # Create plain JS objects (not Maps):
+    obj(a=1, b=2)          # -> { a: 1, b: 2 }
+
+    # With spread syntax:
+    obj(**base, c=3)       # -> { ...base, c: 3 }
+    obj(a=1, **base)       # -> { a: 1, ...base }
+
+    # Empty object:
+    obj()                  # -> {}
+
+Unlike dict() which transpiles to new Map(), obj() creates plain JavaScript
+object literals. Use this for React props, style objects, and anywhere you
+need a plain JS object.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, override
+
+from pulse.transpiler.errors import TranspileError
+from pulse.transpiler.nodes import Expr, Object, Spread, spread_dict
+from pulse.transpiler.vdom import VDOMNode
+
+# TYPE_CHECKING avoids import cycle: Transpiler -> nodes -> Expr -> obj -> Transpiler
+if TYPE_CHECKING:
+	from pulse.transpiler.transpiler import Transpiler
+
+
+@dataclass(slots=True)
+class ObjTransformer(Expr):
+	"""Transformer for obj() with **spread support.
+
+	obj(key=value, ...) -> { key: value, ... }
+	obj(**base, key=value) -> { ...base, key: value }
+
+	Creates a plain JavaScript object literal.
+	Use this instead of dict() when you need a plain object (e.g., for React props).
+	"""
+
+	@override
+	def emit(self, out: list[str]) -> None:
+		raise TypeError("obj cannot be emitted directly - must be called")
+
+	@override
+	def render(self) -> VDOMNode:
+		raise TypeError("obj cannot be rendered - must be called")
+
+	@override
+	def transpile_call(
+		self,
+		args: list[ast.expr],
+		keywords: list[ast.keyword],
+		ctx: Transpiler,
+	) -> Expr:
+		if args:
+			raise TranspileError("obj() only accepts keyword arguments")
+
+		props: list[tuple[str, Expr] | Spread] = []
+		for kw in keywords:
+			if kw.arg is None:
+				# **spread syntax
+				props.append(spread_dict(ctx.emit_expr(kw.value)))
+			else:
+				# key=value
+				props.append((kw.arg, ctx.emit_expr(kw.value)))
+
+		return Object(props)
+
+
+# Create singleton instance for use as a callable
+obj = ObjTransformer()

pulse/js/pulse.py

@@ -0,0 +1,112 @@
+"""
+Pulse UI client bindings for channel communication.
+
+Usage:
+    from pulse.js.pulse import usePulseChannel, ChannelBridge, PulseChannelResetError
+
+    @ps.javascript(jsx=True)
+    def MyChannelComponent(*, channel_id: str):
+        bridge = usePulseChannel(channel_id)
+
+        # Subscribe to events
+        useEffect(
+            lambda: bridge.on("server:notify", lambda payload: console.log(payload)),
+            [bridge],
+        )
+
+        # Emit events to server
+        def send_ping():
+            bridge.emit("client:ping", {"message": "hello"})
+
+        # Make requests to server
+        async def send_request():
+            response = await bridge.request("client:request", {"data": 123})
+            console.log(response)
+
+        return ps.div()[
+            ps.button(onClick=send_ping)["Send Ping"],
+            ps.button(onClick=send_request)["Send Request"],
+        ]
+"""
+
+from collections.abc import Awaitable as _Awaitable
+from collections.abc import Callable as _Callable
+from typing import Any as _Any
+from typing import TypeVar as _TypeVar
+
+from pulse.transpiler.js_module import JsModule
+
+T = _TypeVar("T")
+
+
+class PulseChannelResetError(Exception):
+	"""Error raised when a channel is closed or reset."""
+
+	pass
+
+
+class ChannelBridge:
+	"""A bridge for bidirectional communication between client and server.
+
+	Provides methods for emitting events, making requests, and subscribing
+	to server events on a specific channel.
+	"""
+
+	@property
+	def id(self) -> str:
+		"""The unique channel identifier."""
+		...
+
+	def emit(self, event: str, payload: _Any = None) -> None:
+		"""Emit an event to the server.
+
+		Args:
+		    event: The event name to emit.
+		    payload: Optional data to send with the event.
+		"""
+		...
+
+	def request(self, event: str, payload: _Any = None) -> _Awaitable[_Any]:
+		"""Make a request to the server and await a response.
+
+		Args:
+		    event: The event name to send.
+		    payload: Optional data to send with the request.
+
+		Returns:
+		    A Promise that resolves with the server's response.
+		"""
+		...
+
+	def on(self, event: str, handler: _Callable[[_Any], _Any]) -> _Callable[[], None]:
+		"""Subscribe to events from the server.
+
+		Args:
+		    event: The event name to listen for.
+		    handler: A callback function that receives the event payload.
+		        May be sync or async. For request events, the return value
+		        is sent back to the server.
+
+		Returns:
+		    A cleanup function that unsubscribes the handler.
+		"""
+		...
+
+
+def usePulseChannel(channel_id: str) -> ChannelBridge:
+	"""React hook to connect to a Pulse channel.
+
+	Must be called from within a React component. The channel connection
+	is automatically managed based on component lifecycle.
+
+	Args:
+	    channel_id: The unique identifier for the channel to connect to.
+
+	Returns:
+	    A ChannelBridge instance for interacting with the channel.
+	"""
+	...
+
+
+# Register as a JS module with named imports from pulse-ui-client
+JsModule.register(name="pulse", src="pulse-ui-client", values="named_import")

pulse/js/react.py

@@ -0,0 +1,350 @@
+"""
+JavaScript React module.
+
+Usage:
+    from pulse.js.react import useState, useEffect, useRef
+    state, setState = useState(0)         # -> const [state, setState] = useState(0)
+    useEffect(lambda: print("hi"), [])    # -> useEffect(() => console.log("hi"), [])
+    ref = useRef(None)                    # -> const ref = useRef(null)
+
+    # Also available as namespace:
+    import pulse.js.react as React
+    React.useState(0)                     # -> React.useState(0)
+"""
+
+from collections.abc import Callable as _Callable
+from typing import Any as _Any
+from typing import Protocol as _Protocol
+from typing import TypeVar as _TypeVar
+
+from pulse.transpiler.js_module import JsModule
+
+# Type variables for hooks
+T = _TypeVar("T")
+T_co = _TypeVar("T_co", covariant=True)
+T_contra = _TypeVar("T_contra", contravariant=True)
+S = _TypeVar("S")
+A = _TypeVar("A")
+
+
+# =============================================================================
+# React Types
+# =============================================================================
+
+
+class RefObject(_Protocol[T_co]):
+	"""Type for useRef return value."""
+
+	@property
+	def current(self) -> T_co: ...
+
+
+class MutableRefObject(_Protocol[T]):
+	"""Type for useRef return value with mutable current."""
+
+	@property
+	def current(self) -> T: ...
+
+	@current.setter
+	def current(self, value: T) -> None: ...
+
+
+class Dispatch(_Protocol[T_contra]):
+	"""Type for setState/dispatch functions."""
+
+	def __call__(self, action: T_contra, /) -> None: ...
+
+
+class TransitionStartFunction(_Protocol):
+	"""Type for startTransition callback."""
+
+	def __call__(self, callback: _Callable[[], None], /) -> None: ...
+
+
+class Context(_Protocol[T_co]):
+	"""Type for React Context."""
+
+	@property
+	def Provider(self) -> _Any: ...
+
+	@property
+	def Consumer(self) -> _Any: ...
+
+
+class ReactNode(_Protocol):
+	"""Type for React children."""
+
+	...
+
+
+class ReactElement(_Protocol):
+	"""Type for React element."""
+
+	@property
+	def type(self) -> _Any: ...
+
+	@property
+	def props(self) -> _Any: ...
+
+	@property
+	def key(self) -> str | None: ...
+
+
+# =============================================================================
+# State Hooks
+# =============================================================================
+
+
+def useState(
+	initial_state: S | _Callable[[], S],
+) -> tuple[S, Dispatch[S | _Callable[[S], S]]]:
+	"""Returns a stateful value and a function to update it.
+
+	Example:
+		count, set_count = useState(0)
+		set_count(count + 1)
+		set_count(lambda prev: prev + 1)
+	"""
+	...
+
+
+def useReducer(
+	reducer: _Callable[[S, A], S],
+	initial_arg: S,
+	init: _Callable[[S], S] | None = None,
+) -> tuple[S, Dispatch[A]]:
+	"""An alternative to useState for complex state logic.
+
+	Example:
+		def reducer(state, action):
+			if action['type'] == 'increment':
+				return {'count': state['count'] + 1}
+			return state
+
+		state, dispatch = useReducer(reducer, {'count': 0})
+		dispatch({'type': 'increment'})
+	"""
+	...
+
+
+# =============================================================================
+# Effect Hooks
+# =============================================================================
+
+
+def useEffect(
+	effect: _Callable[[], None | _Callable[[], None]],
+	deps: list[_Any] | None = None,
+) -> None:
+	"""Accepts a function that contains imperative, possibly effectful code.
+
+	Example:
+		useEffect(lambda: print("mounted"), [])
+		useEffect(lambda: (print("update"), lambda: print("cleanup"))[-1], [dep])
+	"""
+	...
+
+
+def useLayoutEffect(
+	effect: _Callable[[], None | _Callable[[], None]],
+	deps: list[_Any] | None = None,
+) -> None:
+	"""Like useEffect, but fires synchronously after all DOM mutations.
+
+	Example:
+		useLayoutEffect(lambda: measure_element(), [])
+	"""
+	...
+
+
+def useInsertionEffect(
+	effect: _Callable[[], None | _Callable[[], None]],
+	deps: list[_Any] | None = None,
+) -> None:
+	"""Like useLayoutEffect, but fires before any DOM mutations.
+	Use for CSS-in-JS libraries.
+	"""
+	...
+
+
+# =============================================================================
+# Ref Hooks
+# =============================================================================
+
+
+def useRef(initial_value: T) -> MutableRefObject[T]:
+	"""Returns a mutable ref object.
+
+	Example:
+		input_ref = useRef(None)
+		# In JSX: <input ref={input_ref} />
+		input_ref.current.focus()
+	"""
+	...
+
+
+def useImperativeHandle(
+	ref: RefObject[T] | _Callable[[T | None], None] | None,
+	create_handle: _Callable[[], T],
+	deps: list[_Any] | None = None,
+) -> None:
+	"""Customizes the instance value exposed to parent components when using ref."""
+	...
+
+
+# =============================================================================
+# Performance Hooks
+# =============================================================================
+
+
+def useMemo(factory: _Callable[[], T], deps: list[_Any]) -> T:
+	"""Returns a memoized value.
+
+	Example:
+		expensive = useMemo(lambda: compute_expensive(a, b), [a, b])
+	"""
+	...
+
+
+def useCallback(callback: T, deps: list[_Any]) -> T:
+	"""Returns a memoized callback.
+
+	Example:
+		handle_click = useCallback(lambda e: print(e), [])
+	"""
+	...
+
+
+def useDeferredValue(value: T) -> T:
+	"""Defers updating a part of the UI. Returns a deferred version of the value."""
+	...
+
+
+def useTransition() -> tuple[bool, TransitionStartFunction]:
+	"""Returns a stateful value for pending state and a function to start transition.
+
+	Example:
+		is_pending, start_transition = useTransition()
+		start_transition(lambda: set_state(new_value))
+	"""
+	...
+
+
+# =============================================================================
+# Context Hooks
+# =============================================================================
+
+
+def useContext(context: Context[T]) -> T:
+	"""Returns the current context value for the given context.
+
+	Example:
+		theme = useContext(ThemeContext)
+	"""
+	...
+
+
+# =============================================================================
+# Other Hooks
+# =============================================================================
+
+
+def useId() -> str:
+	"""Generates a unique ID that is stable across server and client.
+
+	Example:
+		id = useId()
+		# <label htmlFor={id}>Name</label>
+		# <input id={id} />
+	"""
+	...
+
+
+def useDebugValue(value: T, format_fn: _Callable[[T], _Any] | None = None) -> None:
+	"""Displays a label in React DevTools for custom hooks."""
+	...
+
+
+def useSyncExternalStore(
+	subscribe: _Callable[[_Callable[[], None]], _Callable[[], None]],
+	get_snapshot: _Callable[[], T],
+	get_server_snapshot: _Callable[[], T] | None = None,
+) -> T:
+	"""Subscribe to an external store.
+
+	Example:
+		width = useSyncExternalStore(
+			subscribe_to_resize,
+			lambda: window.innerWidth
+		)
+	"""
+	...
+
+
+# =============================================================================
+# React Components and Elements
+# =============================================================================
+
+
+def createElement(
+	type: _Any,
+	props: dict[str, _Any] | None = None,
+	*children: _Any,
+) -> ReactElement:
+	"""Creates a React element."""
+	...
+
+
+def cloneElement(
+	element: ReactElement,
+	props: dict[str, _Any] | None = None,
+	*children: _Any,
+) -> ReactElement:
+	"""Clones and returns a new React element."""
+	...
+
+
+def isValidElement(obj: _Any) -> bool:
+	"""Checks if the object is a React element."""
+	...
+
+
+def memo(component: T, are_equal: _Callable[[_Any, _Any], bool] | None = None) -> T:
+	"""Memoizes a component to skip re-rendering when props are unchanged."""
+	...
+
+
+def forwardRef(
+	render: _Callable[[_Any, _Any], ReactElement | None],
+) -> _Callable[..., ReactElement | None]:
+	"""Lets your component expose a DOM node to a parent component with a ref."""
+	...
+
+
+def lazy(load: _Callable[[], _Any]) -> _Any:
+	"""Lets you defer loading a component's code until it is rendered."""
+	...
+
+
+def createContext(default_value: T) -> Context[T]:
+	"""Creates a Context object."""
+	...
+
+
+# =============================================================================
+# Fragments
+# =============================================================================
+
+
+class Fragment:
+	"""Lets you group elements without a wrapper node."""
+
+	...
+
+
+# =============================================================================
+# Registration
+# =============================================================================
+
+# React is a namespace module where each hook is a named import
+JsModule.register(name="React", src="react", kind="namespace", values="named_import")

pulse/js/react_dom.py

@@ -0,0 +1,30 @@
+"""
+JavaScript ReactDOM module.
+
+Usage:
+    from pulse.js.react_dom import createPortal
+    createPortal(children, container)  # -> createPortal(children, container)
+
+    # Also available as namespace:
+    import pulse.js.react_dom as ReactDOM
+    ReactDOM.createPortal(children, container)
+"""
+
+from typing import Any as _Any
+
+# Import types from react module for consistency
+from pulse.js.react import ReactNode as ReactNode
+from pulse.transpiler.js_module import JsModule
+
+
+def createPortal(
+	children: ReactNode, container: _Any, key: str | None = None
+) -> ReactNode:
+	"""Creates a portal to render children into a different DOM subtree."""
+	...
+
+
+# ReactDOM is a namespace module where each export is a named import
+JsModule.register(
+	name="ReactDOM", src="react-dom", kind="namespace", values="named_import"
+)

pulse/messages.py

@@ -1,7 +1,7 @@
 from typing import Any, Literal, NotRequired, TypedDict
 
 from pulse.routing import RouteInfo
-from pulse.transpiler.vdom import VDOM, VDOMOperation
+from pulse.transpiler.vdom import VDOM, VDOMNode, VDOMOperation
 
 
 # ====================
@@ -80,12 +80,12 @@ class ServerChannelResponseMessage(TypedDict):
 
 
 class ServerJsExecMessage(TypedDict):
-	"""Execute JavaScript code on the client."""
+	"""Execute JavaScript expression on the client."""
 
 	type: Literal["js_exec"]
 	path: str
 	id: str
-	code: str
+	expr: VDOMNode
 
 
 # ====================
@@ -98,20 +98,20 @@ class ClientCallbackMessage(TypedDict):
 	args: list[Any]
 
 
-class ClientMountMessage(TypedDict):
-	type: Literal["mount"]
+class ClientAttachMessage(TypedDict):
+	type: Literal["attach"]
 	path: str
 	routeInfo: RouteInfo
 
 
-class ClientNavigateMessage(TypedDict):
-	type: Literal["navigate"]
+class ClientUpdateMessage(TypedDict):
+	type: Literal["update"]
 	path: str
 	routeInfo: RouteInfo
 
 
-class ClientUnmountMessage(TypedDict):
-	type: Literal["unmount"]
+class ClientDetachMessage(TypedDict):
+	type: Literal["detach"]
 	path: str
 
 
@@ -165,9 +165,9 @@ ServerMessage = (
 
 ClientPulseMessage = (
 	ClientCallbackMessage
-	| ClientMountMessage
-	| ClientNavigateMessage
-	| ClientUnmountMessage
+	| ClientAttachMessage
+	| ClientUpdateMessage
+	| ClientDetachMessage
 	| ClientApiResultMessage
 	| ClientJsResultMessage
 )
@@ -193,5 +193,5 @@ class Directives(TypedDict):
 
 
 class Prerender(TypedDict):
-	views: dict[str, ServerInitMessage | None]
+	views: dict[str, ServerInitMessage | ServerNavigateToMessage | None]
 	directives: Directives

pulse/proxy.py

@@ -15,6 +15,9 @@ from starlette.responses import PlainTextResponse, Response
 from starlette.websockets import WebSocket, WebSocketDisconnect
 from websockets.typing import Subprotocol
 
+from pulse.context import PulseContext
+from pulse.cookies import parse_cookie_header
+
 logger = logging.getLogger(__name__)
 
 
@@ -108,11 +111,7 @@ class ReactProxy:
 			)
 		}
 
-		# Accept the client WebSocket connection first
-		# We'll accept without subprotocol initially, then update if target accepts one
-		await websocket.accept()
-
-		# Connect to target WebSocket server
+		# Connect to target WebSocket server first to negotiate subprotocol
 		try:
 			async with websockets.connect(
 				target_url,
@@ -120,6 +119,9 @@ class ReactProxy:
 				subprotocols=subprotocols,
 				ping_interval=None,  # Let the target server handle ping/pong
 			) as target_ws:
+				# Accept client connection with the negotiated subprotocol
+				await websocket.accept(subprotocol=target_ws.subprotocol)
+
 				# Forward messages bidirectionally
 				async def forward_client_to_target():
 					try:
@@ -190,6 +192,17 @@ class ReactProxy:
 
 		# Extract headers, skip host header (will be set by httpx)
 		headers = {k: v for k, v in request.headers.items() if k.lower() != "host"}
+		ctx = PulseContext.get()
+		session = ctx.session
+		if session is not None:
+			session_cookie = session.get_cookie_value(ctx.app.cookie.name)
+			if session_cookie:
+				existing = parse_cookie_header(headers.get("cookie"))
+				if existing.get(ctx.app.cookie.name) != session_cookie:
+					existing[ctx.app.cookie.name] = session_cookie
+					headers["cookie"] = "; ".join(
+						f"{key}={value}" for key, value in existing.items()
+					)
 
 		try:
 			# Build request