pulse-framework 0.1.62__py3-none-any.whl

pulse/hooks/stable.py

@@ -0,0 +1,138 @@
+from collections.abc import Callable
+from typing import Any, TypeVar, overload
+
+from pulse.hooks.core import MISSING, HookMetadata, HookState, hooks
+
+T = TypeVar("T")
+TCallable = TypeVar("TCallable", bound=Callable[..., Any])
+
+
+class StableEntry:
+	"""Container for a stable value and its wrapper function.
+
+	Holds a value and a wrapper function that always delegates to the
+	current value, allowing the wrapper reference to remain stable while
+	the underlying value can change.
+
+	Attributes:
+		value: The current wrapped value.
+		wrapper: Stable function that delegates to the current value.
+	"""
+
+	__slots__ = ("value", "wrapper")  # pyright: ignore[reportUnannotatedClassAttribute]
+	value: Any
+	wrapper: Callable[..., Any]
+
+	def __init__(self, value: Any) -> None:
+		self.value = value
+
+		def wrapper(*args: Any, **kwargs: Any):
+			current = self.value
+			if callable(current):
+				return current(*args, **kwargs)
+			return current
+
+		self.wrapper = wrapper
+
+
+class StableRegistry(HookState):
+	"""Internal hook state that stores stable entries by key.
+
+	Maintains a dictionary of StableEntry objects, allowing stable
+	wrappers to persist across renders while their underlying values
+	can be updated.
+	"""
+
+	__slots__ = ("entries",)  # pyright: ignore[reportUnannotatedClassAttribute]
+
+	def __init__(self) -> None:
+		super().__init__()
+		self.entries: dict[str, StableEntry] = {}
+
+
+def _stable_factory(*_: object) -> StableRegistry:
+	return StableRegistry()
+
+
+_stable_hook = hooks.create(
+	"pulse:core.stable",
+	_stable_factory,
+	metadata=HookMetadata(
+		owner="pulse.core",
+		description="Internal registry for pulse.stable values",
+	),
+)
+
+
+@overload
+def stable(key: str) -> Any: ...
+
+
+@overload
+def stable(key: str, value: TCallable) -> TCallable: ...
+
+
+@overload
+def stable(key: str, value: T) -> Callable[[], T]: ...
+
+
+def stable(key: str, value: Any = MISSING) -> Any:
+	"""Return a stable wrapper that always calls the latest value.
+
+		Creates a wrapper function that maintains a stable reference across renders
+		while delegating to the current value. Useful for event handlers and callbacks
+		that need to stay referentially stable.
+
+		Args:
+			key: Unique identifier for this stable value within the component.
+			value: Optional value or callable to wrap. If provided, updates the
+				stored value and returns the wrapper. If omitted, returns the
+				existing wrapper for the key.
+
+		Returns:
+			A stable wrapper function that delegates to the current value. If the
+			value is callable, the wrapper calls it with any provided arguments.
+			If not callable, the wrapper returns the value directly.
+
+		Raises:
+			ValueError: If key is empty.
+			KeyError: If value is not provided and no entry exists for the key.
+
+		Example:
+
+		```python
+		def my_component():
+		    s = ps.state("data", lambda: DataState())
+
+		    # Without stable, this would create a new function each render
+		    handle_click = ps.stable("click", lambda: s.increment())
+
+		    return m.Button("Click", on_click=handle_click)
+		```
+
+		Use Cases:
+			- Event handlers passed to child components to prevent unnecessary re-renders
+			- Callbacks registered with external systems
+			- Any function reference that needs to stay stable across renders
+	) -> Any:
+	"""
+	if not key:
+		raise ValueError("stable() requires a non-empty string key")
+
+	registry = _stable_hook()
+	entry = registry.entries.get(key)
+
+	if value is not MISSING:
+		if entry is None:
+			entry = StableEntry(value)
+			registry.entries[key] = entry
+		else:
+			entry.value = value
+		return entry.wrapper
+
+	if entry is None:
+		raise KeyError(f"stable(): no value registered for key '{key}'")
+	return entry.wrapper
+
+
+__all__ = ["stable", "StableRegistry", "StableEntry"]

pulse/hooks/state.py

@@ -0,0 +1,192 @@
+import inspect
+from collections.abc import Callable
+from types import CodeType, FrameType
+from typing import Any, TypeVar, override
+
+from pulse.component import is_component_code
+from pulse.hooks.core import HookMetadata, HookState, hooks
+from pulse.state import State
+
+S = TypeVar("S", bound=State)
+
+
+class StateHookState(HookState):
+	"""Internal hook state for managing State instances across renders.
+
+	Stores State instances keyed by string identifier and tracks which keys
+	have been accessed during the current render cycle.
+	"""
+
+	__slots__ = ("instances", "called_keys")  # pyright: ignore[reportUnannotatedClassAttribute]
+	instances: dict[tuple[str, Any], State]
+	called_keys: set[tuple[str, Any]]
+
+	def __init__(self) -> None:
+		super().__init__()
+		self.instances = {}
+		self.called_keys = set()
+
+	def _make_key(self, identity: Any, key: str | None) -> tuple[str, Any]:
+		if key is None:
+			return ("code", identity)
+		return ("key", key)
+
+	@override
+	def on_render_start(self, render_cycle: int) -> None:
+		super().on_render_start(render_cycle)
+		self.called_keys.clear()
+
+	def get_or_create_state(
+		self,
+		identity: Any,
+		key: str | None,
+		arg: State | Callable[[], State],
+	) -> State:
+		full_identity = self._make_key(identity, key)
+		if full_identity in self.called_keys:
+			if key is None:
+				raise RuntimeError(
+					"`pulse.state` can only be called once per component render at the same location. "
+					+ "Use the `key` parameter to disambiguate: ps.state(..., key=unique_value)"
+				)
+			raise RuntimeError(
+				f"`pulse.state` can only be called once per component render with key='{key}'"
+			)
+		self.called_keys.add(full_identity)
+
+		existing = self.instances.get(full_identity)
+		if existing is not None:
+			# Dispose any State instances passed directly as args that aren't being used
+			if isinstance(arg, State) and arg is not existing:
+				arg.dispose()
+			if existing.__disposed__:
+				key_label = f"key='{key}'" if key is not None else "callsite"
+				raise RuntimeError(
+					"`pulse.state` found a disposed cached State for "
+					+ key_label
+					+ ". Do not dispose states returned by `pulse.state`."
+				)
+			return existing
+
+		# Create new state
+		instance = _instantiate_state(arg)
+		if instance.__disposed__:
+			raise RuntimeError(
+				"`pulse.state` received a disposed State instance. "
+				+ "Do not dispose states passed to `pulse.state`."
+			)
+		self.instances[full_identity] = instance
+		return instance
+
+	@override
+	def dispose(self) -> None:
+		for instance in self.instances.values():
+			try:
+				if not instance.__disposed__:
+					instance.dispose()
+			except RuntimeError:
+				# Already disposed, ignore
+				pass
+		self.instances.clear()
+
+
+def _instantiate_state(arg: State | Callable[[], State]) -> State:
+	instance = arg() if callable(arg) else arg
+	if not isinstance(instance, State):
+		raise TypeError(
+			"`pulse.state` expects a State instance or a callable returning a State instance"
+		)
+	return instance
+
+
+def _state_factory():
+	return StateHookState()
+
+
+def _frame_offset(frame: FrameType) -> int:
+	offset = frame.f_lasti
+	if offset < 0:
+		offset = frame.f_lineno
+	return offset
+
+
+def collect_component_identity(
+	frame: FrameType,
+) -> tuple[tuple[CodeType, int], ...]:
+	identity: list[tuple[CodeType, int]] = []
+	cursor: FrameType | None = frame
+	while cursor is not None:
+		identity.append((cursor.f_code, _frame_offset(cursor)))
+		if is_component_code(cursor.f_code):
+			return tuple(identity)
+		cursor = cursor.f_back
+	return tuple(identity[:1])
+
+
+_state_hook = hooks.create(
+	"pulse:core.state",
+	_state_factory,
+	metadata=HookMetadata(
+		owner="pulse.core",
+		description="Internal storage for pulse.state hook",
+	),
+)
+
+
+def state(
+	arg: S | Callable[[], S],
+	*,
+	key: str | None = None,
+) -> S:
+	"""Get or create a state instance associated with a key or callsite.
+
+	Args:
+		arg: A State instance or a callable that returns a State instance.
+		key: Optional key to disambiguate multiple calls from the same location.
+
+	Returns:
+		The same State instance on subsequent renders with the same key.
+
+	Raises:
+		ValueError: If key is empty.
+		RuntimeError: If called more than once per render with the same key.
+		TypeError: If arg is not a State or callable returning a State.
+
+	Example:
+
+	```python
+	def counter():
+	    s = ps.state("counter", lambda: CounterState())
+	    return m.Button(f"Count: {s.count}", on_click=lambda: s.increment())
+	```
+
+	Notes:
+		- Key must be non-empty string
+		- Can only be called once per render with the same key
+		- Factory is only called on first render; subsequent renders return cached instance
+		- State is disposed when component unmounts
+	"""
+	if key is not None and not isinstance(key, str):
+		raise TypeError("state() key must be a string")
+
+	if key == "":
+		raise ValueError("state() requires a non-empty string key")
+
+	resolved_key = key
+	resolved_arg = arg
+
+	identity: Any
+	if resolved_key is None:
+		frame = inspect.currentframe()
+		assert frame is not None
+		caller = frame.f_back
+		assert caller is not None
+		identity = collect_component_identity(caller)
+	else:
+		identity = resolved_key
+
+	hook_state = _state_hook()
+	return hook_state.get_or_create_state(identity, resolved_key, resolved_arg)  # pyright: ignore[reportReturnType]
+
+
+__all__ = ["state", "StateHookState"]

pulse/js/__init__.py

@@ -0,0 +1,125 @@
+"""JavaScript module bindings for use in @javascript decorated functions (transpiler).
+
+## Usage
+
+Import JS classes (for constructors and static methods):
+
+```python
+from pulse.js import Set, Number, Array, Date, Promise, Map, Error
+Set([1, 2, 3])         # -> new Set([1, 2, 3])
+Number.isFinite(42)    # -> Number.isFinite(42)
+Array.isArray(x)       # -> Array.isArray(x)
+```
+
+Import JS namespace objects (function-only modules):
+
+```python
+from pulse.js import Math, JSON, console, window, document, navigator
+Math.floor(3.7)        # -> Math.floor(3.7)
+JSON.stringify(obj)    # -> JSON.stringify(obj)
+console.log("hi")      # -> console.log("hi")
+```
+
+Alternative: import namespace modules for namespace access:
+
+```python
+import pulse.js.json as JSON
+JSON.stringify(obj)    # -> JSON.stringify(obj)
+```
+
+Statement functions:
+
+```python
+from pulse.js import throw
+throw(Error("message"))  # -> throw Error("message");
+```
+
+Object literals (plain JS objects instead of Map):
+
+```python
+from pulse.js import obj
+obj(a=1, b=2)          # -> { a: 1, b: 2 }
+```
+"""
+
+import importlib as _importlib
+from typing import Any as _Any
+from typing import NoReturn as _NoReturn
+
+from pulse.js.obj import obj as obj
+from pulse.transpiler.nodes import EXPR_REGISTRY as _EXPR_REGISTRY
+from pulse.transpiler.nodes import UNDEFINED as _UNDEFINED
+
+# Namespace modules - return JsModule from registry (handles both builtins and external)
+_MODULE_EXPORTS_NAMESPACE: dict[str, str] = {
+	"JSON": "pulse.js.json",
+	"Math": "pulse.js.math",
+	"React": "pulse.js.react",
+	"console": "pulse.js.console",
+	"window": "pulse.js.window",
+	"document": "pulse.js.document",
+	"navigator": "pulse.js.navigator",
+}
+
+# Class modules - return via getattr to get Class wrapper (emits `new ...`)
+_MODULE_EXPORTS_ATTRIBUTE: dict[str, str] = {
+	"Array": "pulse.js.array",
+	"Date": "pulse.js.date",
+	"Error": "pulse.js.error",
+	"Map": "pulse.js.map",
+	"Object": "pulse.js.object",
+	"Promise": "pulse.js.promise",
+	"React": "pulse.js.react",
+	"RegExp": "pulse.js.regexp",
+	"Set": "pulse.js.set",
+	"String": "pulse.js.string",
+	"WeakMap": "pulse.js.weakmap",
+	"WeakSet": "pulse.js.weakset",
+	"Number": "pulse.js.number",
+}
+
+
+# Statement-like functions (not classes/objects, but callable transformers)
+# Note: throw needs special handling in the transpiler to convert from expression to statement
+class _ThrowExpr:
+	"""Wrapper for throw that can be detected and converted to a statement."""
+
+	def __call__(self, x: _Any) -> _NoReturn:
+		# This will be replaced during transpilation
+		# The transpiler should detect this and emit as a Throw statement
+		raise RuntimeError("throw() can only be used in @javascript functions")
+
+
+throw = _ThrowExpr()
+
+
+# JS primitive values
+undefined = _UNDEFINED
+
+
+# Cache for exported values
+_export_cache: dict[str, _Any] = {}
+
+
+def __getattr__(name: str) -> _Any:
+	"""Lazily import and return JS builtin modules.
+
+	Allows: from pulse.js import Set, Number, Array, etc.
+	"""
+	# Return cached export if already imported
+	if name in _export_cache:
+		return _export_cache[name]
+
+	# Namespace modules: return JsModule (handles attribute access via transpile_getattr)
+	if name in _MODULE_EXPORTS_NAMESPACE:
+		module = _importlib.import_module(_MODULE_EXPORTS_NAMESPACE[name])
+		export = _EXPR_REGISTRY[id(module)]
+	# Class modules: return Class wrapper via getattr (emits `new ...()`)
+	elif name in _MODULE_EXPORTS_ATTRIBUTE:
+		module = _importlib.import_module(_MODULE_EXPORTS_ATTRIBUTE[name])
+		export = getattr(module, name)
+	else:
+		raise AttributeError(f"module 'pulse.js' has no attribute '{name}'")
+
+	_export_cache[name] = export
+	return export

pulse/js/__init__.pyi

@@ -0,0 +1,115 @@
+"""Type stubs for pulse.js module exports.
+
+This file provides type hints for direct imports from pulse.js:
+    from pulse.js import Set, Number, Array, Math, Date, Promise, etc.
+"""
+
+from typing import Any as _Any
+from typing import NoReturn as _NoReturn
+
+import pulse.js.console
+import pulse.js.document
+import pulse.js.json
+import pulse.js.math
+import pulse.js.navigator
+import pulse.js.window
+
+# Re-export type definitions for use in user code
+from pulse.js._types import (
+	Clipboard as Clipboard,
+)
+from pulse.js._types import (
+	ClipboardItem as ClipboardItem,
+)
+from pulse.js._types import (
+	CSSStyleDeclaration as CSSStyleDeclaration,
+)
+from pulse.js._types import (
+	Element as Element,
+)
+from pulse.js._types import (
+	Event as Event,
+)
+from pulse.js._types import (
+	HTMLCollection as HTMLCollection,
+)
+from pulse.js._types import (
+	HTMLElement as HTMLElement,
+)
+from pulse.js._types import (
+	JSIterable as JSIterable,
+)
+from pulse.js._types import (
+	JSIterator as JSIterator,
+)
+from pulse.js._types import (
+	JSIteratorResult as JSIteratorResult,
+)
+from pulse.js._types import (
+	JSONReplacer as JSONReplacer,
+)
+from pulse.js._types import (
+	JSONReviver as JSONReviver,
+)
+from pulse.js._types import (
+	JSONValue as JSONValue,
+)
+from pulse.js._types import (
+	NodeList as NodeList,
+)
+from pulse.js._types import (
+	Range as Range,
+)
+from pulse.js._types import (
+	Selection as Selection,
+)
+
+# Re-export classes with proper generic types
+from pulse.js.array import Array as Array
+from pulse.js.date import Date as Date
+from pulse.js.error import Error as Error
+from pulse.js.error import EvalError as EvalError
+from pulse.js.error import RangeError as RangeError
+from pulse.js.error import ReferenceError as ReferenceError
+from pulse.js.error import SyntaxError as SyntaxError
+from pulse.js.error import TypeError as TypeError
+from pulse.js.error import URIError as URIError
+from pulse.js.map import Map as Map
+from pulse.js.number import Number as Number
+from pulse.js.object import Object as Object
+from pulse.js.object import PropertyDescriptor as PropertyDescriptor
+from pulse.js.promise import Promise as Promise
+from pulse.js.promise import PromiseWithResolvers as PromiseWithResolvers
+from pulse.js.regexp import RegExp as RegExp
+from pulse.js.set import Set as Set
+from pulse.js.string import String as String
+from pulse.js.weakmap import WeakMap as WeakMap
+from pulse.js.weakset import WeakSet as WeakSet
+from pulse.transpiler.nodes import Undefined
+
+# Re-export namespace modules
+console = pulse.js.console
+document = pulse.js.document
+JSON = pulse.js.json
+Math = pulse.js.math
+navigator = pulse.js.navigator
+window = pulse.js.window
+
+# Statement-like functions
+def throw(x: _Any) -> _NoReturn:
+	"""Throw a JavaScript error."""
+	...
+
+def obj(**kwargs: _Any) -> _Any:
+	"""Create a plain JavaScript object literal.
+
+	Use this instead of dict() when you need a plain JS object (e.g., for React style prop).
+
+	Example:
+		style=obj(display="block", color="red")
+		# Transpiles to: style={{ display: "block", color: "red" }}
+	"""
+	...
+
+# Primitive values
+undefined: Undefined