pulse-framework 0.1.62__py3-none-any.whl

pulse/js/weakmap.py

@@ -0,0 +1,53 @@
+"""
+JavaScript WeakMap builtin module.
+
+Usage:
+
+```python
+from pulse.js import WeakMap
+WeakMap()                     # -> new WeakMap()
+WeakMap([[obj, "value"]])    # -> new WeakMap([[obj, "value"]])
+
+# Or import from module directly:
+from pulse.js.weakmap import WeakMap
+```
+"""
+
+from collections.abc import Iterable as _Iterable
+from typing import Generic as _Generic
+from typing import TypeVar as _TypeVar
+
+from pulse.transpiler.js_module import JsModule
+
+K = _TypeVar("K")  # Keys must be objects in JS, but we can't enforce that statically
+V = _TypeVar("V")
+
+
+class WeakMap(_Generic[K, V]):
+	"""JavaScript WeakMap - a collection of key/value pairs with weak key references.
+
+	WeakMap[K, V] holds weak references to keys, allowing garbage collection.
+	Keys must be objects (not primitives).
+	"""
+
+	def __init__(self, iterable: _Iterable[tuple[K, V]] | None = None, /) -> None: ...
+
+	def delete(self, key: K) -> bool:
+		"""Remove a key and its value. Returns True if the key existed."""
+		...
+
+	def get(self, key: K) -> V | None:
+		"""Return the value for a key, or None if not present."""
+		...
+
+	def has(self, key: K) -> bool:
+		"""Return True if the key exists in the WeakMap."""
+		...
+
+	def set(self, key: K, value: V) -> "WeakMap[K, V]":
+		"""Set a key/value pair. Returns the WeakMap for chaining."""
+		...
+
+
+# Self-register this module as a JS builtin (global identifiers)
+JsModule.register(name=None)

pulse/js/weakset.py

@@ -0,0 +1,48 @@
+"""
+JavaScript WeakSet builtin module.
+
+Usage:
+
+```python
+from pulse.js import WeakSet
+WeakSet()                     # -> new WeakSet()
+WeakSet([obj1, obj2])        # -> new WeakSet([obj1, obj2])
+
+# Or import from module directly:
+from pulse.js.weakset import WeakSet
+```
+"""
+
+from collections.abc import Iterable as _Iterable
+from typing import Generic as _Generic
+from typing import TypeVar as _TypeVar
+
+from pulse.transpiler.js_module import JsModule
+
+T = _TypeVar("T")  # Values must be objects in JS, but we can't enforce that statically
+
+
+class WeakSet(_Generic[T]):
+	"""JavaScript WeakSet - a collection of objects with weak references.
+
+	WeakSet[T] holds weak references to values, allowing garbage collection.
+	Values must be objects (not primitives).
+	"""
+
+	def __init__(self, iterable: _Iterable[T] | None = None, /) -> None: ...
+
+	def add(self, value: T) -> "WeakSet[T]":
+		"""Add a value to the WeakSet. Returns the WeakSet for chaining."""
+		...
+
+	def delete(self, value: T) -> bool:
+		"""Remove a value. Returns True if the value existed."""
+		...
+
+	def has(self, value: T) -> bool:
+		"""Return True if the value exists in the WeakSet."""
+		...
+
+
+# Self-register this module as a JS builtin (global identifiers)
+JsModule.register(name=None)

pulse/js/window.py

@@ -0,0 +1,205 @@
+"""Browser window global object.
+
+Usage:
+
+```python
+from pulse.js import window
+window.alert("Hello!")      # -> window.alert("Hello!")
+window.innerWidth           # -> window.innerWidth
+```
+"""
+
+from collections.abc import Callable as _Callable
+from typing import Any as _Any
+
+from pulse.js._types import Element as _Element
+from pulse.js._types import Selection as _Selection
+from pulse.transpiler.js_module import JsModule
+
+# Dimensions
+innerWidth: int
+innerHeight: int
+outerWidth: int
+outerHeight: int
+
+# Scroll position
+scrollX: float
+scrollY: float
+pageXOffset: float  # Alias for scrollX
+pageYOffset: float  # Alias for scrollY
+
+# Screen information
+devicePixelRatio: float
+
+# Location and history (typed as Any since they're complex interfaces)
+location: _Any
+history: _Any
+navigator: _Any
+document: _Any
+
+# Storage
+localStorage: _Any
+sessionStorage: _Any
+
+# Performance
+performance: _Any
+
+
+# Dialog methods
+def alert(message: str = "", /) -> None:
+	"""Display an alert dialog with the given message."""
+	...
+
+
+def confirm(message: str = "", /) -> bool:
+	"""Display a confirmation dialog. Returns True if user clicks OK."""
+	...
+
+
+def prompt(message: str = "", default: str = "", /) -> str | None:
+	"""Display a prompt dialog. Returns input or None if cancelled."""
+	...
+
+
+# Scroll methods
+def scrollTo(x: float | dict[str, float], y: float | None = None, /) -> None:
+	"""Scroll to the given position."""
+	...
+
+
+def scrollBy(x: float | dict[str, float], y: float | None = None, /) -> None:
+	"""Scroll by the given amount."""
+	...
+
+
+def scroll(x: float | dict[str, float], y: float | None = None, /) -> None:
+	"""Alias for scrollTo."""
+	...
+
+
+# Selection
+def getSelection() -> _Selection | None:
+	"""Return the current text selection."""
+	...
+
+
+def getComputedStyle(element: _Element, pseudoElt: str | None = None, /) -> _Any:
+	"""Return the computed style of an element."""
+	...
+
+
+# Focus
+def focus() -> None:
+	"""Give focus to the window."""
+	...
+
+
+def blur() -> None:
+	"""Remove focus from the window."""
+	...
+
+
+# Open/close
+def open(
+	url: str = "",
+	target: str = "_blank",
+	features: str = "",
+	/,
+) -> _Any | None:
+	"""Open a new window. Returns the new window object or None."""
+	...
+
+
+def close() -> None:
+	"""Close the window (only works for windows opened by script)."""
+	...
+
+
+# Timers (these return timer IDs)
+def setTimeout(handler: _Callable[..., None], timeout: int = 0, /, *args: _Any) -> int:
+	"""Schedule a function to run after a delay. Returns timer ID."""
+	...
+
+
+def clearTimeout(timeoutId: int) -> None:
+	"""Cancel a timeout scheduled with setTimeout."""
+	...
+
+
+def setInterval(handler: _Callable[..., None], timeout: int = 0, /, *args: _Any) -> int:
+	"""Schedule a function to run repeatedly. Returns timer ID."""
+	...
+
+
+def clearInterval(intervalId: int) -> None:
+	"""Cancel an interval scheduled with setInterval."""
+	...
+
+
+# Animation
+def requestAnimationFrame(callback: _Callable[[float], None]) -> int:
+	"""Request a callback before the next repaint. Returns request ID."""
+	...
+
+
+def cancelAnimationFrame(requestId: int) -> None:
+	"""Cancel an animation frame request."""
+	...
+
+
+# Event listeners
+def addEventListener(
+	type: str,
+	listener: _Callable[..., None],
+	options: bool | dict[str, bool] | None = None,
+	/,
+) -> None:
+	"""Add an event listener to the window."""
+	...
+
+
+def removeEventListener(
+	type: str,
+	listener: _Callable[..., None],
+	options: bool | dict[str, bool] | None = None,
+	/,
+) -> None:
+	"""Remove an event listener from the window."""
+	...
+
+
+def dispatchEvent(event: _Any) -> bool:
+	"""Dispatch an event to the window."""
+	...
+
+
+# Encoding
+def atob(encoded: str) -> str:
+	"""Decode a base64 encoded string."""
+	...
+
+
+def btoa(data: str) -> str:
+	"""Encode a string as base64."""
+	...
+
+
+# Misc
+def matchMedia(query: str) -> _Any:
+	"""Return a MediaQueryList for the given media query."""
+	...
+
+
+def print_() -> None:
+	"""Open the print dialog."""
+	...
+
+
+def postMessage(
+	message: _Any, targetOrigin: str, transfer: list[_Any] | None = None, /
+) -> None:
+	"""Post a message to another window."""
+	...
+
+
+JsModule.register(name="window")

pulse/messages.py

@@ -0,0 +1,202 @@
+from typing import Any, Literal, NotRequired, TypedDict
+
+from pulse.routing import RouteInfo
+from pulse.transpiler.vdom import VDOM, VDOMNode, VDOMOperation
+
+
+# ====================
+# Server messages
+# ====================
+class ServerInitMessage(TypedDict):
+	type: Literal["vdom_init"]
+	path: str
+	vdom: VDOM
+
+
+class ServerUpdateMessage(TypedDict):
+	type: Literal["vdom_update"]
+	path: str
+	ops: list[VDOMOperation]
+
+
+ServerErrorPhase = Literal[
+	"render", "callback", "mount", "unmount", "navigate", "server", "effect", "connect"
+]
+
+
+class ServerErrorInfo(TypedDict, total=False):
+	# High-level human message
+	message: str
+	# Full stack trace string (server formatted)
+	stack: str
+	# Which phase failed
+	phase: ServerErrorPhase
+	# Optional extra details (callback key, etc.)
+	details: dict[str, Any]
+
+
+class ServerErrorMessage(TypedDict):
+	type: Literal["server_error"]
+	path: str
+	error: ServerErrorInfo
+
+
+class ServerNavigateToMessage(TypedDict):
+	type: Literal["navigate_to"]
+	path: str
+	replace: bool
+	hard: bool
+
+
+class ServerReloadMessage(TypedDict):
+	type: Literal["reload"]
+
+
+class ServerApiCallMessage(TypedDict):
+	type: Literal["api_call"]
+	# Correlation id to match request/response
+	id: str
+	url: str
+	method: str
+	headers: dict[str, str]
+	# Body can be JSON-serializable or None
+	body: Any | None
+	# Whether to include credentials (cookies)
+	credentials: Literal["include", "omit"]
+
+
+class ServerChannelRequestMessage(TypedDict):
+	type: Literal["channel_message"]
+	channel: str
+	event: str
+	payload: Any
+	requestId: NotRequired[str]
+	error: NotRequired[Any]
+
+
+class ServerChannelResponseMessage(TypedDict):
+	type: Literal["channel_message"]
+	channel: str
+	event: None
+	responseTo: str
+	payload: Any
+	error: NotRequired[Any]
+
+
+class ServerJsExecMessage(TypedDict):
+	"""Execute JavaScript expression on the client."""
+
+	type: Literal["js_exec"]
+	path: str
+	id: str
+	expr: VDOMNode
+
+
+# ====================
+# Client messages
+# ====================
+class ClientCallbackMessage(TypedDict):
+	type: Literal["callback"]
+	path: str
+	callback: str
+	args: list[Any]
+
+
+class ClientAttachMessage(TypedDict):
+	type: Literal["attach"]
+	path: str
+	routeInfo: RouteInfo
+
+
+class ClientUpdateMessage(TypedDict):
+	type: Literal["update"]
+	path: str
+	routeInfo: RouteInfo
+
+
+class ClientDetachMessage(TypedDict):
+	type: Literal["detach"]
+	path: str
+
+
+class ClientApiResultMessage(TypedDict):
+	type: Literal["api_result"]
+	id: str
+	ok: bool
+	status: int
+	headers: dict[str, str]
+	body: Any | None
+
+
+class ClientChannelRequestMessage(TypedDict):
+	type: Literal["channel_message"]
+	channel: str
+	event: str
+	payload: Any
+	requestId: NotRequired[str]
+	error: NotRequired[Any]
+
+
+class ClientChannelResponseMessage(TypedDict):
+	type: Literal["channel_message"]
+	channel: str
+	event: None
+	responseTo: str
+	payload: Any
+	error: NotRequired[Any]
+
+
+class ClientJsResultMessage(TypedDict):
+	"""Result of client-side JS execution."""
+
+	type: Literal["js_result"]
+	id: str
+	result: Any
+	error: str | None
+
+
+ServerChannelMessage = ServerChannelRequestMessage | ServerChannelResponseMessage
+ServerMessage = (
+	ServerInitMessage
+	| ServerUpdateMessage
+	| ServerErrorMessage
+	| ServerApiCallMessage
+	| ServerNavigateToMessage
+	| ServerReloadMessage
+	| ServerChannelMessage
+	| ServerJsExecMessage
+)
+
+
+ClientPulseMessage = (
+	ClientCallbackMessage
+	| ClientAttachMessage
+	| ClientUpdateMessage
+	| ClientDetachMessage
+	| ClientApiResultMessage
+	| ClientJsResultMessage
+)
+ClientChannelMessage = ClientChannelRequestMessage | ClientChannelResponseMessage
+ClientMessage = ClientPulseMessage | ClientChannelMessage
+
+
+class PrerenderPayload(TypedDict):
+	paths: list[str]
+	routeInfo: RouteInfo
+	ttlSeconds: NotRequired[float | int]
+	renderId: NotRequired[str]
+
+
+class SocketIODirectives(TypedDict):
+	headers: dict[str, str]
+	auth: dict[str, str]
+
+
+class Directives(TypedDict):
+	headers: dict[str, str]
+	socketio: SocketIODirectives
+
+
+class Prerender(TypedDict):
+	views: dict[str, ServerInitMessage | ServerNavigateToMessage | None]
+	directives: Directives