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

pulse/hooks/stable.py

@@ -8,6 +8,17 @@ 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]
@@ -25,6 +36,13 @@ class StableEntry:
 
 
 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:
@@ -58,7 +76,46 @@ def stable(key: str, value: TCallable) -> TCallable: ...
 def stable(key: str, value: T) -> Callable[[], T]: ...
 
 
-def stable(key: str, value: Any = MISSING):
+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")
 

pulse/hooks/state.py

@@ -1,6 +1,9 @@
+import inspect
 from collections.abc import Callable
-from typing import TypeVar, override
+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
 
@@ -8,42 +11,71 @@ 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[str, State]
-	called_keys: set[str]
+	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, key: str, arg: State | Callable[[], State]) -> State:
-		if key in self.called_keys:
+	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(key)
+		self.called_keys.add(full_identity)
 
-		existing = self.instances.get(key)
+		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:
-				try:
-					if not arg.__disposed__:
-						arg.dispose()
-				except RuntimeError:
-					# Already disposed, ignore
-					pass
+				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)
-		self.instances[key] = instance
+		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
@@ -71,6 +103,26 @@ 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,
@@ -81,25 +133,60 @@ _state_hook = hooks.create(
 )
 
 
-def state(key: str, arg: S | Callable[[], S]) -> S:
-	"""Get or create a state instance associated with the given key.
+def state(
+	arg: S | Callable[[], S],
+	*,
+	key: str | None = None,
+) -> S:
+	"""Get or create a state instance associated with a key or callsite.
 
 	Args:
-		key: A unique string key identifying this state within the component.
 		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 state instance (same instance on subsequent renders with the same key).
+		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 not key:
+	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(key, arg)  # pyright: ignore[reportReturnType]
+	return hook_state.get_or_create_state(identity, resolved_key, resolved_arg)  # pyright: ignore[reportReturnType]
 
 
 __all__ = ["state", "StateHookState"]

pulse/js/__init__.py

@@ -1,29 +1,45 @@
 """JavaScript module bindings for use in @javascript decorated functions (transpiler).
 
-Usage:
-    # Import JS classes (for constructors and static methods):
-    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):
-    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:
-    import pulse.js.json as JSON
-    JSON.stringify(obj)    # -> JSON.stringify(obj)
-
-    # Statement functions:
-    from pulse.js import throw
-    throw(Error("message"))  # -> throw Error("message");
-
-    # Object literals (plain JS objects instead of Map):
-    from pulse.js import obj
-    obj(a=1, b=2)          # -> { a: 1, b: 2 }
+## 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
@@ -39,7 +55,6 @@ _MODULE_EXPORTS_NAMESPACE: dict[str, str] = {
 	"JSON": "pulse.js.json",
 	"Math": "pulse.js.math",
 	"React": "pulse.js.react",
-	"ReactDOM": "pulse.js.react_dom",
 	"console": "pulse.js.console",
 	"window": "pulse.js.window",
 	"document": "pulse.js.document",
@@ -54,6 +69,7 @@ _MODULE_EXPORTS_ATTRIBUTE: dict[str, str] = {
 	"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",

pulse/js/array.py

@@ -2,13 +2,16 @@
 JavaScript Array builtin module.
 
 Usage:
-    from pulse.js import Array
-    Array.isArray([1, 2, 3])      # -> Array.isArray([1, 2, 3])
-    Array.from_([1, 2, 3])        # -> Array.from([1, 2, 3])
-    Array(10)                     # -> new Array(10)
 
-    # Or import from module directly:
-    from pulse.js.array import Array
+```python
+from pulse.js import Array
+Array.isArray([1, 2, 3])      # -> Array.isArray([1, 2, 3])
+Array.from_([1, 2, 3])        # -> Array.from([1, 2, 3])
+Array(10)                     # -> new Array(10)
+
+# Or import from module directly:
+from pulse.js.array import Array
+```
 """
 
 from __future__ import annotations

pulse/js/console.py

@@ -2,18 +2,21 @@
 JavaScript Console builtin module.
 
 Usage:
-    import pulse.js.console as console
-    console.log("Hello")          # -> console.log("Hello")
-    console.error("Error")        # -> console.error("Error")
-    console.assert(True, "msg")   # -> console.assert(True, "msg")
-
-    # Note: For 'assert' (Python keyword), use namespace import:
-    # import pulse.js.console as console; console.assert(...)
-    # Or use the underscore version for direct import:
-    from pulse.js.console import log, error, warn, info, debug, assert_
-    log("Hello")                  # -> console.log("Hello")
-    error("Error")                # -> console.error("Error")
-    assert_(True, "msg")          # -> console.assert(True, "msg")
+
+```python
+import pulse.js.console as console
+console.log("Hello")          # -> console.log("Hello")
+console.error("Error")        # -> console.error("Error")
+console.assert(True, "msg")   # -> console.assert(True, "msg")
+
+# Note: For 'assert' (Python keyword), use namespace import:
+# import pulse.js.console as console; console.assert(...)
+# Or use the underscore version for direct import:
+from pulse.js.console import log, error, warn, info, debug, assert_
+log("Hello")                  # -> console.log("Hello")
+error("Error")                # -> console.error("Error")
+assert_(True, "msg")          # -> console.assert(True, "msg")
+```
 """
 
 from typing import Any as _Any

pulse/js/date.py

@@ -2,13 +2,16 @@
 JavaScript Date builtin module.
 
 Usage:
-    from pulse.js import Date
-    Date()                        # -> new Date()
-    Date.now()                    # -> Date.now()
-    Date.parse("2023-01-01")      # -> Date.parse("2023-01-01")
 
-    # Or import from module directly:
-    from pulse.js.date import Date
+```python
+from pulse.js import Date
+Date()                        # -> new Date()
+Date.now()                    # -> Date.now()
+Date.parse("2023-01-01")      # -> Date.parse("2023-01-01")
+
+# Or import from module directly:
+from pulse.js.date import Date
+```
 """
 
 from typing import Any as _Any

pulse/js/document.py

@@ -1,8 +1,11 @@
 """Browser document global object.
 
 Usage:
-    from pulse.js import document
-    document.querySelector("#app")      # -> document.querySelector("#app")
+
+```python
+from pulse.js import document
+document.querySelector("#app")      # -> document.querySelector("#app")
+```
 """
 
 from collections.abc import Callable as _Callable

pulse/js/error.py

@@ -2,11 +2,14 @@
 JavaScript Error builtin module.
 
 Usage:
-    from pulse.js import Error
-    Error("message")              # -> new Error("message")
 
-    from pulse.js.error import TypeError, RangeError, ReferenceError
-    TypeError("message")         # -> new TypeError("message")
+```python
+from pulse.js import Error
+Error("message")              # -> new Error("message")
+
+from pulse.js.error import TypeError, RangeError, ReferenceError
+TypeError("message")         # -> new TypeError("message")
+```
 """
 
 from pulse.transpiler.js_module import JsModule

pulse/js/json.py

@@ -2,13 +2,16 @@
 JavaScript JSON builtin module.
 
 Usage:
-    import pulse.js.json as JSON
-    JSON.stringify({"a": 1})      # -> JSON.stringify({"a": 1})
-    JSON.parse('{"a": 1}')        # -> JSON.parse('{"a": 1}')
 
-    from pulse.js.json import stringify, parse
-    stringify({"a": 1})           # -> JSON.stringify({"a": 1})
-    parse('{"a": 1}')             # -> JSON.parse('{"a": 1}')
+```python
+import pulse.js.json as JSON
+JSON.stringify({"a": 1})      # -> JSON.stringify({"a": 1})
+JSON.parse('{"a": 1}')        # -> JSON.parse('{"a": 1}')
+
+from pulse.js.json import stringify, parse
+stringify({"a": 1})           # -> JSON.stringify({"a": 1})
+parse('{"a": 1}')             # -> JSON.parse('{"a": 1}')
+```
 """
 
 from collections.abc import Callable as _Callable

pulse/js/map.py

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

pulse/js/math.py

@@ -2,13 +2,16 @@
 JavaScript Math builtin module.
 
 Usage:
-    import pulse.js.math as Math
-    Math.PI           # -> Math.PI
-    Math.floor(3.7)   # -> Math.floor(3.7)
 
-    from pulse.js.math import PI, floor
-    PI                # -> Math.PI
-    floor(3.7)        # -> Math.floor(3.7)
+```python
+import pulse.js.math as Math
+Math.PI           # -> Math.PI
+Math.floor(3.7)   # -> Math.floor(3.7)
+
+from pulse.js.math import PI, floor
+PI                # -> Math.PI
+floor(3.7)        # -> Math.floor(3.7)
+```
 """
 
 from pulse.transpiler.js_module import JsModule

pulse/js/navigator.py

@@ -1,8 +1,11 @@
 """Browser navigator global object.
 
 Usage:
-    from pulse.js import navigator, console
-    console.log(navigator.userAgent)
+
+```python
+from pulse.js import navigator, console
+console.log(navigator.userAgent)
+```
 """
 
 from typing import Any as _Any

pulse/js/number.py

@@ -2,13 +2,16 @@
 JavaScript Number builtin module.
 
 Usage:
-    from pulse.js import Number
-    Number.isFinite(42)       # -> Number.isFinite(42)
-    Number.MAX_SAFE_INTEGER   # -> Number.MAX_SAFE_INTEGER
-    Number(x)                 # -> new Number(x)
 
-    # Or import from module directly:
-    from pulse.js.number import Number
+```python
+from pulse.js import Number
+Number.isFinite(42)       # -> Number.isFinite(42)
+Number.MAX_SAFE_INTEGER   # -> Number.MAX_SAFE_INTEGER
+Number(x)                 # -> new Number(x)
+
+# Or import from module directly:
+from pulse.js.number import Number
+```
 """
 
 from typing import Any as _Any

pulse/js/obj.py

@@ -2,19 +2,22 @@
 JavaScript object literal creation.
 
 Usage:
-    from pulse.js import obj
 
-    # Create plain JS objects (not Maps):
-    obj(a=1, b=2)          # -> { a: 1, b: 2 }
+```python
+from pulse.js import obj
 
-    # With spread syntax:
-    obj(**base, c=3)       # -> { ...base, c: 3 }
-    obj(a=1, **base)       # -> { a: 1, ...base }
+# Create plain JS objects (not Maps):
+obj(a=1, b=2)          # -> { a: 1, b: 2 }
 
-    # Empty object:
-    obj()                  # -> {}
+# With spread syntax:
+obj(**base, c=3)       # -> { ...base, c: 3 }
+obj(a=1, **base)       # -> { a: 1, ...base }
 
-Unlike dict() which transpiles to new Map(), obj() creates plain JavaScript
+# Empty object:
+obj()                  # -> {}
+```
+
+Unlike `dict()` which transpiles to `new Map()`, `obj()` creates plain JavaScript
 object literals. Use this for React props, style objects, and anywhere you
 need a plain JS object.
 """
@@ -36,13 +39,13 @@ if TYPE_CHECKING:
 
 @dataclass(slots=True)
 class ObjTransformer(Expr):
-	"""Transformer for obj() with **spread support.
+	"""Transformer for `obj()` with `**spread` support.
 
-	obj(key=value, ...) -> { key: value, ... }
-	obj(**base, key=value) -> { ...base, key: value }
+	- `obj(key=value, ...)` -> `{ key: value, ... }`
+	- `obj(**base, key=value)` -> `{ ...base, key: value }`
 
 	Creates a plain JavaScript object literal.
-	Use this instead of dict() when you need a plain object (e.g., for React props).
+	Use this instead of `dict()` when you need a plain object (e.g., for React props).
 	"""
 
 	@override

pulse/js/object.py

@@ -2,13 +2,16 @@
 JavaScript Object builtin module.
 
 Usage:
-    from pulse.js import Object
-    Object.keys({"a": 1})         # -> Object.keys({"a": 1})
-    Object.assign({}, {"a": 1})   # -> Object.assign({}, {"a": 1})
-    Object.is_(x, y)              # -> Object.is(x, y)
 
-    # Or import from module directly:
-    from pulse.js.object import Object
+```python
+from pulse.js import Object
+Object.keys({"a": 1})         # -> Object.keys({"a": 1})
+Object.assign({}, {"a": 1})   # -> Object.assign({}, {"a": 1})
+Object.is_(x, y)              # -> Object.is(x, y)
+
+# Or import from module directly:
+from pulse.js.object import Object
+```
 """
 
 from collections.abc import Iterable as _Iterable