pulse-framework 0.1.44__py3-none-any.whl → 0.1.47__py3-none-any.whl

pulse/queries/store.py

@@ -1,10 +1,11 @@
 import datetime as dt
-from collections.abc import Awaitable, Callable
+from collections.abc import Callable
 from typing import Any, TypeVar, cast
 
+from pulse.helpers import MISSING
 from pulse.queries.common import QueryKey
 from pulse.queries.infinite_query import InfiniteQuery, Page
-from pulse.queries.query import RETRY_DELAY_DEFAULT, Query
+from pulse.queries.query import RETRY_DELAY_DEFAULT, KeyedQuery
 
 T = TypeVar("T")
 
@@ -15,26 +16,25 @@ class QueryStore:
 	"""
 
 	def __init__(self):
-		self._entries: dict[QueryKey, Query[Any] | InfiniteQuery[Any, Any]] = {}
+		self._entries: dict[QueryKey, KeyedQuery[Any] | InfiniteQuery[Any, Any]] = {}
 
 	def items(self):
 		"""Iterate over all (key, query) pairs in the store."""
 		return self._entries.items()
 
-	def get_any(self, key: QueryKey) -> Query[Any] | InfiniteQuery[Any, Any] | None:
+	def get_any(self, key: QueryKey):
 		"""Get any query (regular or infinite) by key, or None if not found."""
 		return self._entries.get(key)
 
 	def ensure(
 		self,
 		key: QueryKey,
-		fetch_fn: Callable[[], Awaitable[T]],
-		initial_data: T | None = None,
+		initial_data: T | None = MISSING,
 		initial_data_updated_at: float | dt.datetime | None = None,
 		gc_time: float = 300.0,
 		retries: int = 3,
 		retry_delay: float = RETRY_DELAY_DEFAULT,
-	) -> Query[T]:
+	) -> KeyedQuery[T]:
 		# Return existing entry if present
 		existing = self._entries.get(key)
 		if existing:
@@ -42,15 +42,14 @@ class QueryStore:
 				raise TypeError(
 					"Query key is already used for an infinite query; cannot reuse for regular query"
 				)
-			return cast(Query[T], existing)
+			return cast(KeyedQuery[T], existing)
 
-		def _on_dispose(e: Query[Any]) -> None:
+		def _on_dispose(e: KeyedQuery[Any]) -> None:
 			if e.key in self._entries and self._entries[e.key] is e:
 				del self._entries[e.key]
 
-		entry = Query(
+		entry = KeyedQuery(
 			key,
-			fetch_fn,
 			initial_data=initial_data,
 			initial_data_updated_at=initial_data_updated_at,
 			gc_time=gc_time,
@@ -61,7 +60,7 @@ class QueryStore:
 		self._entries[key] = entry
 		return entry
 
-	def get(self, key: QueryKey) -> Query[Any] | None:
+	def get(self, key: QueryKey) -> KeyedQuery[Any] | None:
 		"""
 		Get an existing regular query by key, or None if not found.
 		"""
@@ -82,7 +81,6 @@ class QueryStore:
 	def ensure_infinite(
 		self,
 		key: QueryKey,
-		query_fn: Callable[[Any], Awaitable[Any]],
 		*,
 		initial_page_param: Any,
 		get_next_page_param: Callable[[list[Page[Any, Any]]], Any | None],
@@ -108,7 +106,6 @@ class QueryStore:
 
 		entry = InfiniteQuery(
 			key,
-			query_fn,
 			initial_page_param=initial_page_param,
 			get_next_page_param=get_next_page_param,
 			get_previous_page_param=get_previous_page_param,

pulse/react_component.py

@@ -13,6 +13,7 @@ from types import UnionType
 from typing import (
 	Annotated,
 	Any,
+	ClassVar,
 	Generic,
 	Literal,
 	ParamSpec,
@@ -24,9 +25,18 @@ from typing import (
 	override,
 )
 
-from pulse.codegen.imports import Imported, ImportStatement
 from pulse.helpers import Sentinel
 from pulse.reactive_extensions import unwrap
+from pulse.transpiler.errors import JSCompilationError
+from pulse.transpiler.imports import Import
+from pulse.transpiler.nodes import (
+	JSExpr,
+	JSMember,
+	JSSpread,
+	JSXElement,
+	JSXProp,
+	JSXSpreadProp,
+)
 from pulse.vdom import Child, Element, Node
 
 T = TypeVar("T")
@@ -295,25 +305,112 @@ def default_fn_signature_without_children(
 ) -> Element: ...
 
 
-class ReactComponent(Generic[P], Imported):
+# ----------------------------------------------------------------------------
+# JSX transpilation helpers
+# ----------------------------------------------------------------------------
+
+
+def _build_jsx_props(kwargs: dict[str, Any]) -> list[JSXProp | JSXSpreadProp]:
+	"""Build JSX props list from kwargs dict.
+
+	Kwargs maps:
+	- "propName" -> value for named props
+	- "__spread_N" -> JSSpread(expr) for spread props
+	"""
+	props: list[JSXProp | JSXSpreadProp] = []
+	for key, value in kwargs.items():
+		if isinstance(value, JSSpread):
+			props.append(JSXSpreadProp(value.expr))
+		else:
+			props.append(JSXProp(key, JSExpr.of(value)))
+	return props
+
+
+def _flatten_children(items: list[Any], out: list[JSExpr | JSXElement | str]) -> None:
+	"""Flatten arrays and handle spreads in children list."""
+	from pulse.transpiler.nodes import JSArray, JSString
+
+	for it in items:
+		# Convert raw values first
+		it = JSExpr.of(it) if not isinstance(it, JSExpr) else it
+		if isinstance(it, JSArray):
+			_flatten_children(list(it.elements), out)
+		elif isinstance(it, JSSpread):
+			out.append(it.expr)
+		elif isinstance(it, JSString):
+			out.append(it.value)
+		else:
+			out.append(it)
+
+
+class ReactComponentCallExpr(JSExpr):
+	"""JSX call expression for a ReactComponent.
+
+	Created when a ReactComponent is called with props. Supports subscripting
+	to add children, producing the final JSXElement.
+	"""
+
+	is_jsx: ClassVar[bool] = True
+	component: "ReactComponent[...]"
+	props: tuple[JSXProp | JSXSpreadProp, ...]
+	children: tuple[str | JSExpr | JSXElement, ...]
+
+	def __init__(
+		self,
+		component: "ReactComponent[...]",
+		props: tuple[JSXProp | JSXSpreadProp, ...],
+		children: tuple[str | JSExpr | JSXElement, ...],
+	) -> None:
+		self.component = component
+		self.props = props
+		self.children = children
+
+	@override
+	def emit(self) -> str:
+		return JSXElement(self.component, self.props, self.children).emit()
+
+	@override
+	def emit_subscript(self, indices: list[Any]) -> JSExpr:
+		"""Handle Component(props...)[children] -> JSXElement."""
+		extra_children: list[JSExpr | JSXElement | str] = []
+		_flatten_children(indices, extra_children)
+		all_children = list(self.children) + extra_children
+		return JSXElement(self.component, self.props, all_children)
+
+	@override
+	def emit_call(self, args: list[Any], kwargs: dict[str, Any]) -> JSExpr:
+		"""Calling an already-called component is an error."""
+		raise JSCompilationError(
+			f"Cannot call <{self.component.name}> - already called. "
+			+ "Use subscript for children: Component(props...)[children]"
+		)
+
+
+class ReactComponent(JSExpr, Generic[P]):
 	"""
 	A React component that can be used within the UI tree.
 	Returns a function that creates mount point UITreeNode instances.
 
 	Args:
-	    tag: Name of the component (or "default" for default export)
-	    import_path: Module path to import the component from
-	    alias: Optional alias for the component in the registry
+	    name: Name of the component (or "default" for default export)
+	    src: Module path to import the component from
 	    is_default: True if this is a default export, else named export
-	    import_name: If specified, import this name from import_path and access tag as a property of it
+	    prop: Optional property name to access the component from the imported object
+	    lazy: Whether to lazy load the component
+	    version: Optional npm semver constraint for this component's package
+	    prop_spec: Optional PropSpec for the component
+	    fn_signature: Function signature to parse for props
+	    extra_imports: Additional imports to include (CSS files, etc.)
 
 	Returns:
 	    A function that creates Node instances with mount point tags
 	"""
 
+	import_: Import
 	props_spec: PropSpec
 	fn_signature: Callable[P, Element]
 	lazy: bool
+	_prop: str | None  # Property access like AppShell.Header
 
 	def __init__(
 		self,
@@ -326,11 +423,14 @@ class ReactComponent(Generic[P], Imported):
 		version: str | None = None,
 		prop_spec: PropSpec | None = None,
 		fn_signature: Callable[P, Element] = default_signature,
-		extra_imports: tuple[ImportStatement, ...]
-		| list[ImportStatement]
-		| None = None,
+		extra_imports: tuple[Import, ...] | list[Import] | None = None,
 	):
-		super().__init__(name, src, is_default=is_default, prop=prop)
+		# Create the Import directly (prop is stored separately on ReactComponent)
+		if is_default:
+			self.import_ = Import.default(name, src)
+		else:
+			self.import_ = Import.named(name, src)
+		self._prop = prop
 
 		# Build props_spec from fn_signature if provided and props not provided
 		if prop_spec:
@@ -347,10 +447,62 @@ class ReactComponent(Generic[P], Imported):
 		self.lazy = lazy
 		# Optional npm semver constraint for this component's package
 		self.version: str | None = version
-		# Additional import statements to include in route where this component is used
-		self.extra_imports: list[ImportStatement] = list(extra_imports or [])
+		# Additional imports to include in route where this component is used
+		self.extra_imports: list[Import] = list(extra_imports or [])
 		COMPONENT_REGISTRY.get().add(self)
 
+	@override
+	def emit(self) -> str:
+		if self.prop:
+			return JSMember(self.import_, self.prop).emit()
+		return self.import_.emit()
+
+	@override
+	def emit_call(self, args: list[Any], kwargs: dict[str, Any]) -> JSExpr:
+		"""Handle Component(props...) -> ReactComponentCallExpr."""
+		props_list = _build_jsx_props(kwargs)
+		children_list: list[JSExpr | JSXElement | str] = []
+		_flatten_children(args, children_list)
+		return ReactComponentCallExpr(self, tuple(props_list), tuple(children_list))
+
+	@override
+	def emit_subscript(self, indices: list[Any]) -> JSExpr:
+		"""Direct subscript on ReactComponent is not allowed.
+
+		Use Component(props...)[children] instead of Component[children].
+		"""
+		raise JSCompilationError(
+			f"Cannot subscript ReactComponent '{self.name}' directly. "
+			+ "Use Component(props...)[children] or Component()[children] instead."
+		)
+
+	@property
+	def name(self) -> str:
+		return self.import_.name
+
+	@property
+	def src(self) -> str:
+		return self.import_.src
+
+	@property
+	def is_default(self) -> bool:
+		return self.import_.is_default
+
+	@property
+	def prop(self) -> str | None:
+		return self._prop
+
+	@property
+	def expr(self) -> str:
+		"""Expression for the component in the registry and VDOM tags.
+
+		Uses the import's js_name (with unique ID suffix) to match the
+		unified registry on the client side.
+		"""
+		if self.prop:
+			return f"{self.import_.js_name}.{self.prop}"
+		return self.import_.js_name
+
 	@override
 	def __repr__(self) -> str:
 		default_part = ", default=True" if self.is_default else ""
@@ -359,7 +511,8 @@ class ReactComponent(Generic[P], Imported):
 		props_part = f", props_spec={self.props_spec!r}"
 		return f"ReactComponent(name='{self.name}', src='{self.src}'{prop_part}{default_part}{lazy_part}{props_part})"
 
-	def __call__(self, *children: P.args, **props: P.kwargs) -> Node:
+	@override
+	def __call__(self, *children: P.args, **props: P.kwargs) -> Node:  # pyright: ignore[reportIncompatibleMethodOverride]
 		key = props.get("key")
 		if key is not None and not isinstance(key, str):
 			raise ValueError("key must be a string or None")
@@ -806,7 +959,7 @@ def react_component(
 	is_default: bool = False,
 	lazy: bool = False,
 	version: str | None = None,
-	extra_imports: list[ImportStatement] | None = None,
+	extra_imports: list[Import] | None = None,
 ) -> Callable[[Callable[P, None] | Callable[P, Element]], ReactComponent[P]]:
 	"""
 	Decorator to define a React component wrapper. The decorated function is

pulse/reactive.py

@@ -191,7 +191,8 @@ class Computed(Generic[T_co]):
 				if len(scope.effects) > 0:
 					raise RuntimeError(
 						"An effect was created within a computed variable's function. "
-						+ "This behavior is not allowed, computed variables should be pure calculations."
+						+ "This is most likely unintended. If you need to create an effect here, "
+						+ "wrap the effect creation with Untrack()."
 					)
 			finally:
 				self.on_stack = False
@@ -274,6 +275,7 @@ class Effect(Disposable):
 	_interval_handle: asyncio.TimerHandle | None
 	explicit_deps: bool
 	batch: "Batch | None"
+	paused: bool
 
 	def __init__(
 		self,
@@ -301,6 +303,7 @@ class Effect(Disposable):
 		self._lazy = lazy
 		self._interval = interval
 		self._interval_handle = None
+		self.paused = False
 
 		if immediate and lazy:
 			raise ValueError("An effect cannot be boht immediate and lazy")
@@ -358,7 +361,20 @@ class Effect(Disposable):
 			self._interval_handle.cancel()
 			self._interval_handle = None
 
+	def pause(self):
+		"""Pause the effect - it won't run when dependencies change."""
+		self.paused = True
+		self.cancel(cancel_interval=True)
+
+	def resume(self):
+		"""Resume a paused effect and schedule it to run."""
+		if self.paused:
+			self.paused = False
+			self.schedule()
+
 	def schedule(self):
+		if self.paused:
+			return
 		# Immediate effects run right away when scheduled and do not enter a batch
 		if self.immediate:
 			self.run()
@@ -383,6 +399,8 @@ class Effect(Disposable):
 			self._cancel_interval()
 
 	def push_change(self):
+		if self.paused:
+			return
 		# Short-circuit if already scheduled in a batch.
 		# This avoids redundant schedule() calls and O(n) list checks
 		# when the same effect is reached through multiple dependency paths.

pulse/reactive_extensions.py

@@ -45,7 +45,7 @@ class SupportsKeysAndGetItem(Protocol[T1, T2_co]):
 
 # Return an iterable view that subscribes to per-key signals during iteration
 class ReactiveDictItems(Generic[T1, T2]):
-	__slots__: tuple[str, ...] = ("_host",)
+	__slots__ = ("_host",)  # pyright: ignore[reportUnannotatedClassAttribute]
 	_host: ReactiveDict[T1, T2]
 
 	def __init__(self, host: ReactiveDict[T1, T2]) -> None:
@@ -60,7 +60,7 @@ class ReactiveDictItems(Generic[T1, T2]):
 
 
 class ReactiveDictValues(Generic[T1, T2]):
-	__slots__: tuple[str, ...] = ("_host",)
+	__slots__ = ("_host",)  # pyright: ignore[reportUnannotatedClassAttribute]
 	_host: ReactiveDict[T1, T2]
 
 	def __init__(self, host: ReactiveDict[T1, T2]) -> None:
@@ -84,7 +84,7 @@ class ReactiveDict(dict[T1, T2]):
 	- Iteration, membership checks, and len are reactive to structural changes
 	"""
 
-	__slots__: tuple[str, ...] = ("_signals", "_structure")
+	__slots__ = ("_signals", "_structure")  # pyright: ignore[reportUnannotatedClassAttribute]
 
 	def __init__(self, initial: Mapping[T1, T2] | None = None) -> None:
 		super().__init__()
@@ -409,7 +409,7 @@ class ReactiveList(list[T1]):
 	- len() subscribes to structural changes
 	"""
 
-	__slots__: tuple[str, ...] = ("_signals", "_structure")
+	__slots__ = ("_signals", "_structure")  # pyright: ignore[reportUnannotatedClassAttribute]
 
 	def __init__(self, initial: Iterable[T1] | None = None) -> None:
 		super().__init__()
@@ -645,7 +645,7 @@ class ReactiveSet(set[T1]):
 	- Iteration subscribes to membership signals for all elements
 	"""
 
-	__slots__: tuple[str, ...] = ("_signals",)
+	__slots__ = ("_signals",)  # pyright: ignore[reportUnannotatedClassAttribute]
 
 	def __init__(self, initial: Iterable[T1] | None = None) -> None:
 		super().__init__()