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

pulse/js/promise.py

@@ -2,15 +2,18 @@
 JavaScript Promise builtin module.
 
 Usage:
-    from pulse.js import Promise
-    Promise(executor)             # -> new Promise(executor)
-    Promise.resolve(value)        # -> Promise.resolve(value)
-    Promise.reject(reason)        # -> Promise.reject(reason)
 
-    # Or import from module directly:
-    from pulse.js.promise import Promise
+```python
+from pulse.js import Promise
+Promise(executor)             # -> new Promise(executor)
+Promise.resolve(value)        # -> Promise.resolve(value)
+Promise.reject(reason)        # -> Promise.reject(reason)
 
-The Promise class is generic and supports async/await via the Awaitable protocol.
+# Or import from module directly:
+from pulse.js.promise import Promise
+```
+
+The `Promise` class is generic and supports async/await via the Awaitable protocol.
 """
 
 from collections.abc import Callable as _Callable
@@ -36,16 +39,19 @@ PromiseSettledResult = PromiseFulfilledResult[T] | PromiseRejectedResult
 class Promise(_Generic[T_co]):
 	"""JavaScript Promise - a thenable that represents an async operation.
 
-	Promise is both generic over its resolved type and implements Awaitable,
+	`Promise` is both generic over its resolved type and implements `Awaitable`,
 	allowing it to be used with Python's async/await syntax which transpiles
 	to JavaScript async/await.
 
 	Example:
-	    @javascript
-	    async def fetch_data() -> str:
-	        response: Promise[Response] = fetch("/api/data")
-	        data = await response  # Awaits the promise
-	        return data.text()
+
+	```python
+	@javascript
+	async def fetch_data() -> str:
+	    response: Promise[Response] = fetch("/api/data")
+	    data = await response  # Awaits the promise
+	    return data.text()
+	```
 	"""
 
 	def __init__(

pulse/js/pulse.py

@@ -2,31 +2,34 @@
 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"],
-        ]
+
+```python
+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

pulse/js/react.py

@@ -2,22 +2,40 @@
 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)
+
+```python
+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)
+```
 """
 
+import ast as _ast
 from collections.abc import Callable as _Callable
+from typing import TYPE_CHECKING as _TYPE_CHECKING
 from typing import Any as _Any
 from typing import Protocol as _Protocol
 from typing import TypeVar as _TypeVar
+from typing import override as _override
 
+from pulse.component import component as _component
+from pulse.transpiler import Import as _Import
+from pulse.transpiler.errors import TranspileError as _TranspileError
+from pulse.transpiler.function import Constant as _Constant
 from pulse.transpiler.js_module import JsModule
+from pulse.transpiler.nodes import Call as _Call
+from pulse.transpiler.nodes import Expr as _Expr
+from pulse.transpiler.nodes import Jsx as _Jsx
+from pulse.transpiler.nodes import Node as _PulseNode
+from pulse.transpiler.vdom import VDOMNode as _VDOMNode
+
+if _TYPE_CHECKING:
+	from pulse.transpiler.transpiler import Transpiler as _Transpiler
 
 # Type variables for hooks
 T = _TypeVar("T")
@@ -101,9 +119,12 @@ def useState(
 	"""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)
+
+	```python
+	count, set_count = useState(0)
+	set_count(count + 1)
+	set_count(lambda prev: prev + 1)
+	```
 	"""
 	...
 
@@ -113,16 +134,19 @@ def useReducer(
 	initial_arg: S,
 	init: _Callable[[S], S] | None = None,
 ) -> tuple[S, Dispatch[A]]:
-	"""An alternative to useState for complex state logic.
+	"""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'})
+	```python
+	def reducer(state, action):
+	    if action['type'] == 'increment':
+	        return {'count': state['count'] + 1}
+	    return state
+
+	state, dispatch = useReducer(reducer, {'count': 0})
+	dispatch({'type': 'increment'})
+	```
 	"""
 	...
 
@@ -139,8 +163,11 @@ def useEffect(
 	"""Accepts a function that contains imperative, possibly effectful code.
 
 	Example:
-		useEffect(lambda: print("mounted"), [])
-		useEffect(lambda: (print("update"), lambda: print("cleanup"))[-1], [dep])
+
+	```python
+	useEffect(lambda: print("mounted"), [])
+	useEffect(lambda: (print("update"), lambda: print("cleanup"))[-1], [dep])
+	```
 	"""
 	...
 
@@ -149,10 +176,13 @@ def useLayoutEffect(
 	effect: _Callable[[], None | _Callable[[], None]],
 	deps: list[_Any] | None = None,
 ) -> None:
-	"""Like useEffect, but fires synchronously after all DOM mutations.
+	"""Like `useEffect`, but fires synchronously after all DOM mutations.
 
 	Example:
-		useLayoutEffect(lambda: measure_element(), [])
+
+	```python
+	useLayoutEffect(lambda: measure_element(), [])
+	```
 	"""
 	...
 
@@ -176,9 +206,12 @@ 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()
+
+	```python
+	input_ref = useRef(None)
+	# In JSX: <input ref={input_ref} />
+	input_ref.current.focus()
+	```
 	"""
 	...
 
@@ -201,7 +234,10 @@ def useMemo(factory: _Callable[[], T], deps: list[_Any]) -> T:
 	"""Returns a memoized value.
 
 	Example:
-		expensive = useMemo(lambda: compute_expensive(a, b), [a, b])
+
+	```python
+	expensive = useMemo(lambda: compute_expensive(a, b), [a, b])
+	```
 	"""
 	...
 
@@ -210,7 +246,10 @@ def useCallback(callback: T, deps: list[_Any]) -> T:
 	"""Returns a memoized callback.
 
 	Example:
-		handle_click = useCallback(lambda e: print(e), [])
+
+	```python
+	handle_click = useCallback(lambda e: print(e), [])
+	```
 	"""
 	...
 
@@ -224,8 +263,11 @@ 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))
+
+	```python
+	is_pending, start_transition = useTransition()
+	start_transition(lambda: set_state(new_value))
+	```
 	"""
 	...
 
@@ -239,7 +281,10 @@ def useContext(context: Context[T]) -> T:
 	"""Returns the current context value for the given context.
 
 	Example:
-		theme = useContext(ThemeContext)
+
+	```python
+	theme = useContext(ThemeContext)
+	```
 	"""
 	...
 
@@ -253,9 +298,12 @@ 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} />
+
+	```python
+	id = useId()
+	# <label htmlFor={id}>Name</label>
+	# <input id={id} />
+	```
 	"""
 	...
 
@@ -273,10 +321,13 @@ def useSyncExternalStore(
 	"""Subscribe to an external store.
 
 	Example:
-		width = useSyncExternalStore(
-			subscribe_to_resize,
-			lambda: window.innerWidth
-		)
+
+	```python
+	width = useSyncExternalStore(
+	    subscribe_to_resize,
+	    lambda: window.innerWidth
+	)
+	```
 	"""
 	...
 
@@ -321,9 +372,102 @@ def forwardRef(
 	...
 
 
-def lazy(load: _Callable[[], _Any]) -> _Any:
-	"""Lets you defer loading a component's code until it is rendered."""
-	...
+class _LazyComponentFactory(_Expr):
+	"""React.lazy binding that works both at definition time and in `@javascript`.
+
+	This Expr represents React's `lazy` function. It can be:
+	- Called at Python definition time: `lazy(factory)` → `Jsx(Constant(...))`
+	- Used as a reference in `@javascript`: `some_fn(lazy)` → `some_fn(lazy)`
+	- Called inside `@javascript`: `lazy(factory)` → creates `Constant+Jsx`
+
+	Usage:
+
+	```python
+	# At definition time (Python executes this)
+	LazyChart = lazy(Import("Chart", "./Chart", lazy=True))
+
+	# As reference in transpiled code
+	@javascript
+	def foo():
+	    return higher_order_fn(lazy)  # → higher_order_fn(lazy)
+
+	# Called in transpiled code
+	@javascript
+	def bar():
+	    LazyComp = lazy(factory)  # → const LazyComp_1 = lazy(factory)
+	    return LazyComp()
+	```
+	"""
+
+	__slots__: tuple[str, ...] = ("_lazy_import",)
+	_lazy_import: _Import | None
+
+	def __init__(self) -> None:
+		# Defer Import creation to avoid polluting global import registry at module load
+		self._lazy_import = None
+
+	@property
+	def _import(self) -> _Import:
+		"""Lazily create the React.lazy import."""
+		if self._lazy_import is None:
+			self._lazy_import = _Import("lazy", "react")
+		return self._lazy_import
+
+	def _create_lazy_component(self, factory: _Expr) -> _Jsx:
+		"""Create a lazy-loaded component from a factory expression.
+
+		Args:
+			factory: An Expr that evaluates to a dynamic import factory
+
+		Returns:
+			A Jsx-wrapped lazy component
+		"""
+		lazy_call = _Call(self._import, [factory])
+		const = _Constant(lazy_call, lazy_call)
+		return _Jsx(const)
+
+	@_override
+	def emit(self, out: list[str]) -> None:
+		"""Emit as reference to the lazy import."""
+		self._import.emit(out)
+
+	@_override
+	def render(self) -> _VDOMNode:
+		raise TypeError("lazy cannot be rendered to VDOM")
+
+	@_override
+	def transpile_call(
+		self,
+		args: list[_ast.expr],
+		keywords: list[_ast.keyword],
+		ctx: "_Transpiler",
+	) -> _Expr:
+		"""Handle lazy(factory) calls in @javascript functions."""
+		if keywords:
+			raise _TranspileError("lazy() does not accept keyword arguments")
+		if len(args) != 1:
+			raise _TranspileError("lazy() takes exactly 1 argument")
+
+		factory = ctx.emit_expr(args[0])
+		return self._create_lazy_component(factory)
+
+	@_override
+	def __call__(self, factory: _Import) -> _Jsx:  # pyright: ignore[reportIncompatibleMethodOverride]
+		"""Python-time call: create a lazy-loaded component.
+
+		Args:
+			factory: An Import with lazy=True that generates a dynamic import factory
+
+		Returns:
+			A Jsx-wrapped lazy component that can be used as LazyChart(props)[children]
+		"""
+		return self._create_lazy_component(factory)
+
+
+# Singleton instance - use as: lazy(Import(...))
+lazy: _LazyComponentFactory = _LazyComponentFactory()
+# Register so transpiler can resolve it from closure
+_Expr.register(lazy, lazy)
 
 
 def createContext(default_value: T) -> Context[T]:
@@ -332,13 +476,15 @@ def createContext(default_value: T) -> Context[T]:
 
 
 # =============================================================================
-# Fragments
+# Components (stub declarations become Jsx-wrapped imports)
 # =============================================================================
 
 
-class Fragment:
-	"""Lets you group elements without a wrapper node."""
-
+@_component
+def Suspense(
+	*, fallback: ReactNode | _PulseNode | None = None, name: str | None = None
+) -> ReactElement:
+	"""Lets you display a fallback while its children are loading."""
 	...
 
 

pulse/js/regexp.py

@@ -2,11 +2,14 @@
 JavaScript RegExp builtin module.
 
 Usage:
-    from pulse.js import RegExp
-    RegExp(pattern, flags)        # -> new RegExp(pattern, flags)
 
-    # Or import from module directly:
-    from pulse.js.regexp import RegExp
+```python
+from pulse.js import RegExp
+RegExp(pattern, flags)        # -> new RegExp(pattern, flags)
+
+# Or import from module directly:
+from pulse.js.regexp import RegExp
+```
 """
 
 from pulse.transpiler.js_module import JsModule

pulse/js/set.py

@@ -2,12 +2,15 @@
 JavaScript Set builtin module.
 
 Usage:
-    from pulse.js import Set
-    Set()                         # -> new Set()
-    Set([1, 2, 3])               # -> new Set([1, 2, 3])
 
-    # Or import from module directly:
-    from pulse.js.set import Set
+```python
+from pulse.js import Set
+Set()                         # -> new Set()
+Set([1, 2, 3])               # -> new Set([1, 2, 3])
+
+# Or import from module directly:
+from pulse.js.set import Set
+```
 """
 
 from collections.abc import Callable as _Callable

pulse/js/string.py

@@ -2,13 +2,16 @@
 JavaScript String builtin module.
 
 Usage:
-    from pulse.js import String
-    String(x)                      # -> new String(x)
-    String.fromCharCode(65)        # -> String.fromCharCode(65)
-    String.fromCodePoint(0x1F600)  # -> String.fromCodePoint(0x1F600)
 
-    # Or import from module directly:
-    from pulse.js.string import String
+```python
+from pulse.js import String
+String(x)                      # -> new String(x)
+String.fromCharCode(65)        # -> String.fromCharCode(65)
+String.fromCodePoint(0x1F600)  # -> String.fromCodePoint(0x1F600)
+
+# Or import from module directly:
+from pulse.js.string import String
+```
 """
 
 from typing import Any as _Any

pulse/js/weakmap.py

@@ -2,12 +2,15 @@
 JavaScript WeakMap builtin module.
 
 Usage:
-    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
+```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

pulse/js/weakset.py

@@ -2,12 +2,15 @@
 JavaScript WeakSet builtin module.
 
 Usage:
-    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
+```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

pulse/js/window.py

@@ -1,9 +1,12 @@
 """Browser window global object.
 
 Usage:
-    from pulse.js import window
-    window.alert("Hello!")      # -> window.alert("Hello!")
-    window.innerWidth           # -> window.innerWidth
+
+```python
+from pulse.js import window
+window.alert("Hello!")      # -> window.alert("Hello!")
+window.innerWidth           # -> window.innerWidth
+```
 """
 
 from collections.abc import Callable as _Callable

pulse/messages.py

@@ -48,6 +48,10 @@ class ServerNavigateToMessage(TypedDict):
 	hard: bool
 
 
+class ServerReloadMessage(TypedDict):
+	type: Literal["reload"]
+
+
 class ServerApiCallMessage(TypedDict):
 	type: Literal["api_call"]
 	# Correlation id to match request/response
@@ -158,6 +162,7 @@ ServerMessage = (
 	| ServerErrorMessage
 	| ServerApiCallMessage
 	| ServerNavigateToMessage
+	| ServerReloadMessage
 	| ServerChannelMessage
 	| ServerJsExecMessage
 )