pulse-framework 0.1.62__py3-none-any.whl

pulse/components/for_.py

@@ -0,0 +1,83 @@
+"""For loop component for mapping items to elements.
+
+Provides a declarative way to render lists, similar to JavaScript's Array.map().
+"""
+
+from collections.abc import Callable, Iterable
+from inspect import Parameter, signature
+from typing import TYPE_CHECKING, Any, TypeVar, overload
+
+from pulse.transpiler.nodes import Call, Element, Expr, Member, transformer
+
+if TYPE_CHECKING:
+	from pulse.transpiler.transpiler import Transpiler
+
+T = TypeVar("T")
+
+
+@transformer("For")
+def emit_for(items: Any, fn: Any, *, ctx: "Transpiler") -> Expr:
+	"""For(items, fn) -> items.map(fn)"""
+	items_expr = ctx.emit_expr(items)
+	fn_expr = ctx.emit_expr(fn)
+	return Call(Member(items_expr, "map"), [fn_expr])
+
+
+@overload
+def For(items: Iterable[T], fn: Callable[[T], Element]) -> list[Element]: ...
+
+
+@overload
+def For(items: Iterable[T], fn: Callable[[T, int], Element]) -> list[Element]: ...
+
+
+def For(items: Iterable[T], fn: Callable[..., Element]) -> list[Element]:
+	"""Map items to elements, like JavaScript's Array.map().
+
+	Iterates over `items` and calls `fn` for each one, returning a list of
+	elements. The mapper function can accept either one argument (item) or
+	two arguments (item, index).
+
+	Args:
+		items: Iterable of items to map over.
+		fn: Mapper function that receives `(item)` or `(item, index)` and
+			returns an Element. If `fn` has a `*args` parameter, it receives
+			both item and index.
+
+	Returns:
+		A list of Elements, one for each item.
+
+	Example:
+		Single argument (item only)::
+
+			ps.For(users, lambda user: UserCard(user=user, key=user.id))
+
+		With index::
+
+			ps.For(items, lambda item, i: ps.li(f"{i}: {item}", key=str(i)))
+
+	Note:
+		In transpiled `@javascript` code, `For` compiles to `.map()`.
+	"""
+	try:
+		sig = signature(fn)
+		has_varargs = any(
+			p.kind == Parameter.VAR_POSITIONAL for p in sig.parameters.values()
+		)
+		num_positional = sum(
+			1
+			for p in sig.parameters.values()
+			if p.kind in (Parameter.POSITIONAL_ONLY, Parameter.POSITIONAL_OR_KEYWORD)
+		)
+		accepts_two = has_varargs or num_positional >= 2
+	except (ValueError, TypeError):
+		# Builtins or callables without inspectable signature: default to single-arg
+		accepts_two = False
+
+	if accepts_two:
+		return [fn(item, idx) for idx, item in enumerate(items)]
+	return [fn(item) for item in items]
+
+
+# Register For in EXPR_REGISTRY so it can be used in transpiled functions
+Expr.register(For, emit_for)

pulse/components/if_.py

@@ -0,0 +1,86 @@
+"""Conditional rendering component.
+
+Provides a declarative way to conditionally render elements based on a condition.
+"""
+
+from collections.abc import Iterable
+from typing import Any, TypeVar
+
+from pulse.reactive import Computed, Signal
+from pulse.transpiler.nodes import Element
+
+T1 = TypeVar("T1", bound=Element | Iterable[Element])
+T2 = TypeVar("T2", bound=Element | Iterable[Element] | None)
+
+
+def _is_truthy(value: Any) -> bool:
+	if isinstance(value, bool):
+		return value
+	if value is None:
+		return False
+	try:
+		return bool(value)
+	except Exception:
+		pass
+	# Fallbacks for array/dataframe-like values that have ambiguous truthiness
+	try:
+		return len(value) > 0  # type: ignore[arg-type]
+	except Exception:
+		pass
+	size = getattr(value, "size", None)
+	if isinstance(size, int):
+		return size > 0
+	empty = getattr(value, "empty", None)
+	if isinstance(empty, bool):
+		return not empty
+	# Conservative fallback
+	return False
+
+
+def If(
+	condition: bool | Signal[bool] | Computed[bool],
+	then: T1,
+	else_: T2 = None,
+) -> T1 | T2:
+	"""Conditional rendering helper.
+
+	Returns `then` if the condition is truthy, otherwise returns `else_`.
+	Automatically unwraps reactive values (Signal, Computed) before evaluation.
+
+	Args:
+		condition: A boolean or reactive value to evaluate. Supports `Signal[bool]`
+			and `Computed[bool]` which are automatically unwrapped.
+		then: Element to render when condition is truthy.
+		else_: Element to render when condition is falsy. Defaults to None.
+
+	Returns:
+		The `then` value if condition is truthy, otherwise `else_`.
+
+	Example:
+		Basic conditional::
+
+			ps.If(
+				user.is_admin,
+				then=AdminPanel(),
+				else_=ps.p("Access denied"),
+			)
+
+		With reactive condition::
+
+			is_visible = ps.Signal(True)
+			ps.If(is_visible, then=ps.div("Content"))
+	"""
+	# Unwrap reactive condition if needed and coerce to bool explicitly with guards
+	if isinstance(condition, (Signal, Computed)):
+		try:
+			raw = condition.unwrap()  # type: ignore[attr-defined]
+		except Exception:
+			try:
+				raw = condition()
+			except Exception:
+				raw = condition
+	else:
+		raw = condition
+	if _is_truthy(raw):
+		return then
+	return else_

pulse/components/react_router.py

@@ -0,0 +1,94 @@
+"""React Router components for client-side navigation.
+
+Provides Pulse bindings for react-router's Link and Outlet components.
+"""
+
+from typing import Literal, TypedDict, Unpack
+
+from pulse.dom.props import HTMLAnchorProps
+from pulse.react_component import react_component
+from pulse.transpiler import Import
+from pulse.transpiler.nodes import Node
+
+
+class LinkPath(TypedDict):
+	"""TypedDict for Link's `to` prop when using an object instead of string."""
+
+	pathname: str
+	search: str
+	hash: str
+
+
+@react_component(Import("Link", "react-router", version="^7"))
+def Link(
+	*children: Node,
+	key: str | None = None,
+	to: str,
+	discover: Literal["render", "none"] | None = None,
+	prefetch: Literal["none", "intent", "render", "viewport"] = "intent",
+	preventScrollReset: bool | None = None,
+	relative: Literal["route", "path"] | None = None,
+	reloadDocument: bool | None = None,
+	replace: bool | None = None,
+	state: dict[str, object] | None = None,
+	viewTransition: bool | None = None,
+	**props: Unpack[HTMLAnchorProps],
+) -> None:
+	"""Client-side navigation link using react-router.
+
+	Renders an anchor tag that performs client-side navigation without a full
+	page reload. Supports prefetching and various navigation behaviors.
+
+	Args:
+		*children: Content to render inside the link.
+		key: React reconciliation key.
+		to: The target URL path (e.g., "/dashboard", "/users/123").
+		discover: Route discovery behavior. "render" discovers on render,
+			"none" disables discovery.
+		prefetch: Prefetch strategy. "intent" (default) prefetches on hover/focus,
+			"render" prefetches immediately, "viewport" when visible, "none" disables.
+		preventScrollReset: If True, prevents scroll position reset on navigation.
+		relative: Path resolution mode. "route" resolves relative to route hierarchy,
+			"path" resolves relative to URL path.
+		reloadDocument: If True, performs a full page navigation instead of SPA.
+		replace: If True, replaces current history entry instead of pushing.
+		state: Arbitrary state to pass to the destination location.
+		viewTransition: If True, enables View Transitions API for the navigation.
+		**props: Additional HTML anchor attributes (className, onClick, etc.).
+
+	Example:
+		Basic navigation::
+
+			ps.Link(to="/dashboard")["Go to Dashboard"]
+
+		With prefetching disabled::
+
+			ps.Link(to="/settings", prefetch="none")["Settings"]
+	"""
+	...
+
+
+@react_component(Import("Outlet", "react-router", version="^7"))
+def Outlet(key: str | None = None) -> None:
+	"""Renders the matched child route's element.
+
+	Outlet is used in parent route components to render their child routes.
+	It acts as a placeholder where nested route content will be displayed.
+
+	Args:
+		key: React reconciliation key.
+
+	Example:
+		Layout with outlet for child routes::
+
+			@ps.component
+			def Layout():
+				return ps.div(
+					ps.nav("Navigation"),
+					ps.Outlet(),  # Child route renders here
+				)
+	"""
+	...
+
+
+__all__ = ["Link", "Outlet"]

pulse/context.py

@@ -0,0 +1,108 @@
+# pyright: reportImportCycles=false
+from contextvars import ContextVar, Token
+from dataclasses import dataclass
+from types import TracebackType
+from typing import TYPE_CHECKING, Literal
+
+from pulse.routing import RouteContext
+
+if TYPE_CHECKING:
+	from pulse.app import App
+	from pulse.render_session import RenderSession
+	from pulse.user_session import UserSession
+
+
+@dataclass
+class PulseContext:
+	"""Composite context accessible to hooks and internals.
+
+	Manages per-request state via context variables. Provides access to the
+	application instance, user session, render session, and route context.
+
+	Attributes:
+		app: Application instance.
+		session: Per-user session (UserSession or None).
+		render: Per-connection render session (RenderSession or None).
+		route: Active route context (RouteContext or None).
+
+	Example:
+		```python
+		ctx = PulseContext(app=app, session=session)
+		with ctx:
+			# Context is active here
+			current = PulseContext.get()
+		# Previous context restored
+		```
+	"""
+
+	app: "App"
+	session: "UserSession | None" = None
+	render: "RenderSession | None" = None
+	route: "RouteContext | None" = None
+	_token: "Token[PulseContext | None] | None" = None
+
+	@classmethod
+	def get(cls) -> "PulseContext":
+		"""Get the current context.
+
+		Returns:
+			Current PulseContext instance.
+
+		Raises:
+			RuntimeError: If no context is active.
+		"""
+		ctx = PULSE_CONTEXT.get()
+		if ctx is None:
+			raise RuntimeError("Internal error: PULSE_CONTEXT is not set")
+		return ctx
+
+	@classmethod
+	def update(
+		cls,
+		session: "UserSession | None" = None,
+		render: "RenderSession | None" = None,
+		route: "RouteContext | None" = None,
+	) -> "PulseContext":
+		"""Create a new context with updated values.
+
+		Inherits unspecified values from the current context.
+
+		Args:
+			session: New session (optional, inherits if not provided).
+			render: New render session (optional, inherits if not provided).
+			route: New route context (optional, inherits if not provided).
+
+		Returns:
+			New PulseContext instance with updated values.
+		"""
+		ctx = cls.get()
+		return PulseContext(
+			app=ctx.app,
+			session=session or ctx.session,
+			render=render or ctx.render,
+			route=route or ctx.route,
+		)
+
+	def __enter__(self):
+		self._token = PULSE_CONTEXT.set(self)
+		return self
+
+	def __exit__(
+		self,
+		exc_type: type[BaseException] | None = None,
+		exc_val: BaseException | None = None,
+		exc_tb: TracebackType | None = None,
+	) -> Literal[False]:
+		if self._token is not None:
+			PULSE_CONTEXT.reset(self._token)
+			self._token = None
+		return False
+
+
+PULSE_CONTEXT: ContextVar["PulseContext | None"] = ContextVar(
+	"pulse_context", default=None
+)
+
+__all__ = [
+	"PULSE_CONTEXT",
+]

pulse/cookies.py

@@ -0,0 +1,322 @@
+from collections.abc import Sequence
+from dataclasses import KW_ONLY, dataclass
+from typing import TYPE_CHECKING, Any, Literal, TypedDict
+from urllib.parse import urlparse
+
+from fastapi import Request, Response
+
+from pulse.env import PulseEnv
+from pulse.hooks.runtime import set_cookie
+
+if TYPE_CHECKING:
+	from pulse.app import PulseMode
+
+
+@dataclass
+class Cookie:
+	"""Configuration for HTTP cookies used in session management.
+
+	Attributes:
+		name: Cookie name.
+		domain: Cookie domain. Set automatically in subdomain mode.
+		secure: HTTPS-only flag. Auto-resolved from server address if None.
+		samesite: SameSite attribute ("lax", "strict", or "none").
+		max_age_seconds: Cookie lifetime in seconds (default 7 days).
+
+	Example:
+		```python
+		cookie = Cookie(
+			name="session",
+			secure=True,
+			samesite="strict",
+			max_age_seconds=3600,
+		)
+		```
+	"""
+
+	name: str
+	_: KW_ONLY
+	domain: str | None = None
+	secure: bool | None = None
+	samesite: Literal["lax", "strict", "none"] = "lax"
+	max_age_seconds: int = 7 * 24 * 3600
+
+	def get_from_fastapi(self, request: Request) -> str | None:
+		"""Extract cookie value from a FastAPI Request.
+
+		Reads the Cookie header and parses it to find this cookie's value.
+
+		Args:
+			request: FastAPI/Starlette Request object.
+
+		Returns:
+			Cookie value if found, None otherwise.
+		"""
+		header = request.headers.get("cookie")
+		cookies = parse_cookie_header(header)
+		return cookies.get(self.name)
+
+	def get_from_socketio(self, environ: dict[str, Any]) -> str | None:
+		"""Extract cookie value from a Socket.IO environ mapping.
+
+		Args:
+			environ: Socket.IO environ dictionary.
+
+		Returns:
+			Cookie value if found, None otherwise.
+		"""
+		raw = environ.get("HTTP_COOKIE") or environ.get("COOKIE")
+		cookies = parse_cookie_header(raw)
+		return cookies.get(self.name)
+
+	async def set_through_api(self, value: str) -> None:
+		"""Set the cookie on the client via WebSocket.
+
+		Must be called during a callback context.
+
+		Args:
+			value: Cookie value to set.
+
+		Raises:
+			RuntimeError: If Cookie.secure is not resolved (ensure App.setup()
+				ran first).
+		"""
+		if self.secure is None:
+			raise RuntimeError(
+				"Cookie.secure is not resolved. Ensure App.setup() ran or set Cookie(secure=True/False)."
+			)
+		await set_cookie(
+			name=self.name,
+			value=value,
+			domain=self.domain,
+			secure=self.secure,
+			samesite=self.samesite,
+			max_age_seconds=self.max_age_seconds,
+		)
+
+	def set_on_fastapi(self, response: Response, value: str) -> None:
+		"""Set the cookie on a FastAPI Response object.
+
+		Configured with httponly=True and path="/".
+
+		Args:
+			response: FastAPI Response object.
+			value: Cookie value to set.
+
+		Raises:
+			RuntimeError: If Cookie.secure is not resolved.
+		"""
+		if self.secure is None:
+			raise RuntimeError(
+				"Cookie.secure is not resolved. Ensure App.setup() ran or set Cookie(secure=True/False)."
+			)
+		response.set_cookie(
+			key=self.name,
+			value=value,
+			httponly=True,
+			samesite=self.samesite,
+			secure=self.secure,
+			max_age=self.max_age_seconds,
+			domain=self.domain,
+			path="/",
+		)
+
+
+@dataclass
+class SetCookie(Cookie):
+	"""Extended Cookie dataclass that includes the cookie value.
+
+	Used for setting cookies with a specific value. Inherits all configuration
+	from Cookie.
+
+	Attributes:
+		value: The cookie value to set.
+	"""
+
+	value: str
+
+	@classmethod
+	def from_cookie(cls, cookie: Cookie, value: str) -> "SetCookie":
+		"""Create a SetCookie from an existing Cookie configuration.
+
+		Args:
+			cookie: Cookie configuration to copy settings from.
+			value: Cookie value to set.
+
+		Returns:
+			SetCookie instance with the same configuration and specified value.
+
+		Raises:
+			RuntimeError: If cookie.secure is not resolved.
+		"""
+		if cookie.secure is None:
+			raise RuntimeError(
+				"Cookie.secure is not resolved. Ensure App.setup() ran or set Cookie(secure=True/False)."
+			)
+		return cls(
+			name=cookie.name,
+			value=value,
+			domain=cookie.domain,
+			secure=cookie.secure,
+			samesite=cookie.samesite,
+			max_age_seconds=cookie.max_age_seconds,
+		)
+
+
+def session_cookie(
+	mode: "PulseMode",
+	name: str = "pulse.sid",
+	max_age_seconds: int = 7 * 24 * 3600,
+):
+	if mode == "single-server":
+		return Cookie(
+			name,
+			domain=None,
+			secure=None,
+			samesite="lax",
+			max_age_seconds=max_age_seconds,
+		)
+	elif mode == "subdomains":
+		return Cookie(
+			name,
+			domain=None,  # to be set later
+			secure=True,
+			samesite="lax",
+			max_age_seconds=max_age_seconds,
+		)
+	else:
+		raise ValueError(f"Unexpected cookie mode: '{mode}'")
+
+
+class CORSOptions(TypedDict, total=False):
+	"""TypedDict for CORS middleware configuration.
+
+	Attributes:
+		allow_origins: List of allowed origins. Use ['*'] for all. Default: ().
+		allow_methods: List of allowed HTTP methods. Default: ('GET',).
+		allow_headers: List of allowed HTTP headers. Default: ().
+		allow_credentials: Whether to allow credentials. Default: False.
+		allow_origin_regex: Regex pattern for allowed origins. Default: None.
+		expose_headers: List of headers to expose to browser. Default: ().
+		max_age: Browser CORS cache duration in seconds. Default: 600.
+	"""
+
+	allow_origins: Sequence[str]
+	"List of allowed origins. Use ['*'] to allow all origins. Default: ()"
+
+	allow_methods: Sequence[str]
+	"List of allowed HTTP methods. Use ['*'] to allow all methods. Default: ('GET',)"
+
+	allow_headers: Sequence[str]
+	"List of allowed HTTP headers. Use ['*'] to allow all headers. Default: ()"
+
+	allow_credentials: bool
+	"Whether to allow credentials (cookies, authorization headers etc). Default: False"
+
+	allow_origin_regex: str | None
+	"Regex pattern for allowed origins. Alternative to allow_origins list. Default: None"
+
+	expose_headers: Sequence[str]
+	"List of headers to expose to the browser. Default: ()"
+
+	max_age: int
+	"How long browsers should cache CORS responses, in seconds. Default: 600"
+
+
+def _parse_host(server_address: str) -> str | None:
+	try:
+		if not server_address:
+			return None
+		host = urlparse(server_address).hostname
+		return host
+	except Exception:
+		return None
+
+
+def _base_domain(host: str) -> str:
+	# Simplified rule: drop the leftmost label, keep everything to the right.
+	# Assumes host is a subdomain (e.g., api.example.com -> example.com).
+	i = host.find(".")
+	return host[i + 1 :] if i != -1 else host
+
+
+def compute_cookie_domain(mode: "PulseMode", server_address: str) -> str | None:
+	host = _parse_host(server_address)
+	if mode == "single-server" or not host:
+		return None
+	if mode == "subdomains":
+		return "." + _base_domain(host)
+	return None
+
+
+def compute_cookie_secure(env: PulseEnv, server_address: str | None) -> bool:
+	scheme = urlparse(server_address or "").scheme.lower()
+	if scheme in ("https", "wss"):
+		secure = True
+	elif scheme in ("http", "ws"):
+		secure = False
+	else:
+		secure = None
+	if secure is None:
+		if env in ("prod", "ci"):
+			raise RuntimeError(
+				"Could not determine cookie security from server_address. "
+				+ "Use an explicit https:// server_address or set Cookie(secure=True/False)."
+			)
+		return False
+	if env in ("prod", "ci") and not secure:
+		raise RuntimeError(
+			"Refusing to use insecure cookies in prod/ci. "
+			+ "Use an https server_address or set Cookie(secure=True) explicitly."
+		)
+	return secure
+
+
+def cors_options(mode: "PulseMode", server_address: str) -> CORSOptions:
+	host = _parse_host(server_address) or "localhost"
+	opts: CORSOptions = {
+		"allow_credentials": True,
+		"allow_methods": ["*"],
+		"allow_headers": ["*"],
+	}
+	if mode == "subdomains":
+		base = _base_domain(host)
+		# Escape dots in base domain for regex (doesn't affect localhost since it has no dots)
+		base = base.replace(".", r"\.")
+		# Allow any subdomain and any port for the base domain
+		opts["allow_origin_regex"] = rf"^https?://([a-z0-9-]+\\.)?{base}(:\\d+)?$"
+		return opts
+	elif mode == "single-server":
+		# For single-server mode, allow same origin
+		# Escape dots in host for regex (doesn't affect localhost since it has no dots)
+		host = host.replace(".", r"\.")
+		opts["allow_origin_regex"] = rf"^https?://{host}(:\\d+)?$"
+		return opts
+	else:
+		raise ValueError(f"Unsupported deployment mode '{mode}'")
+
+
+def parse_cookie_header(header: str | None) -> dict[str, str]:
+	"""Parse a raw Cookie header string into a dictionary.
+
+	Args:
+		header: Raw Cookie header string (e.g., "session=abc123; theme=dark").
+
+	Returns:
+		Dictionary of cookie name-value pairs.
+
+	Example:
+		```python
+		cookies = parse_cookie_header("session=abc123; theme=dark")
+		# {"session": "abc123", "theme": "dark"}
+		```
+	"""
+	cookies: dict[str, str] = {}
+	if not header:
+		return cookies
+	parts = [p.strip() for p in header.split(";") if p.strip()]
+	for part in parts:
+		if "=" in part:
+			k, v = part.split("=", 1)
+			cookies[k.strip()] = v.strip()
+	return cookies