pulse-framework 0.1.62__py3-none-any.whl

pulse/js/react.py

@@ -0,0 +1,495 @@
+"""
+JavaScript React module.
+
+Usage:
+
+```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
+
+if _TYPE_CHECKING:
+	from pulse.transpiler.transpiler import Transpiler as _Transpiler
+
+# Type variables for hooks
+T = _TypeVar("T")
+T_co = _TypeVar("T_co", covariant=True)
+T_contra = _TypeVar("T_contra", contravariant=True)
+S = _TypeVar("S")
+A = _TypeVar("A")
+
+
+# =============================================================================
+# React Types
+# =============================================================================
+
+
+class RefObject(_Protocol[T_co]):
+	"""Type for useRef return value."""
+
+	@property
+	def current(self) -> T_co: ...
+
+
+class MutableRefObject(_Protocol[T]):
+	"""Type for useRef return value with mutable current."""
+
+	@property
+	def current(self) -> T: ...
+
+	@current.setter
+	def current(self, value: T) -> None: ...
+
+
+class Dispatch(_Protocol[T_contra]):
+	"""Type for setState/dispatch functions."""
+
+	def __call__(self, action: T_contra, /) -> None: ...
+
+
+class TransitionStartFunction(_Protocol):
+	"""Type for startTransition callback."""
+
+	def __call__(self, callback: _Callable[[], None], /) -> None: ...
+
+
+class Context(_Protocol[T_co]):
+	"""Type for React Context."""
+
+	@property
+	def Provider(self) -> _Any: ...
+
+	@property
+	def Consumer(self) -> _Any: ...
+
+
+class ReactNode(_Protocol):
+	"""Type for React children."""
+
+	...
+
+
+class ReactElement(_Protocol):
+	"""Type for React element."""
+
+	@property
+	def type(self) -> _Any: ...
+
+	@property
+	def props(self) -> _Any: ...
+
+	@property
+	def key(self) -> str | None: ...
+
+
+# =============================================================================
+# State Hooks
+# =============================================================================
+
+
+def useState(
+	initial_state: S | _Callable[[], S],
+) -> tuple[S, Dispatch[S | _Callable[[S], S]]]:
+	"""Returns a stateful value and a function to update it.
+
+	Example:
+
+	```python
+	count, set_count = useState(0)
+	set_count(count + 1)
+	set_count(lambda prev: prev + 1)
+	```
+	"""
+	...
+
+
+def useReducer(
+	reducer: _Callable[[S, A], S],
+	initial_arg: S,
+	init: _Callable[[S], S] | None = None,
+) -> tuple[S, Dispatch[A]]:
+	"""An alternative to `useState` for complex state logic.
+
+	Example:
+
+	```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'})
+	```
+	"""
+	...
+
+
+# =============================================================================
+# Effect Hooks
+# =============================================================================
+
+
+def useEffect(
+	effect: _Callable[[], None | _Callable[[], None]],
+	deps: list[_Any] | None = None,
+) -> None:
+	"""Accepts a function that contains imperative, possibly effectful code.
+
+	Example:
+
+	```python
+	useEffect(lambda: print("mounted"), [])
+	useEffect(lambda: (print("update"), lambda: print("cleanup"))[-1], [dep])
+	```
+	"""
+	...
+
+
+def useLayoutEffect(
+	effect: _Callable[[], None | _Callable[[], None]],
+	deps: list[_Any] | None = None,
+) -> None:
+	"""Like `useEffect`, but fires synchronously after all DOM mutations.
+
+	Example:
+
+	```python
+	useLayoutEffect(lambda: measure_element(), [])
+	```
+	"""
+	...
+
+
+def useInsertionEffect(
+	effect: _Callable[[], None | _Callable[[], None]],
+	deps: list[_Any] | None = None,
+) -> None:
+	"""Like useLayoutEffect, but fires before any DOM mutations.
+	Use for CSS-in-JS libraries.
+	"""
+	...
+
+
+# =============================================================================
+# Ref Hooks
+# =============================================================================
+
+
+def useRef(initial_value: T) -> MutableRefObject[T]:
+	"""Returns a mutable ref object.
+
+	Example:
+
+	```python
+	input_ref = useRef(None)
+	# In JSX: <input ref={input_ref} />
+	input_ref.current.focus()
+	```
+	"""
+	...
+
+
+def useImperativeHandle(
+	ref: RefObject[T] | _Callable[[T | None], None] | None,
+	create_handle: _Callable[[], T],
+	deps: list[_Any] | None = None,
+) -> None:
+	"""Customizes the instance value exposed to parent components when using ref."""
+	...
+
+
+# =============================================================================
+# Performance Hooks
+# =============================================================================
+
+
+def useMemo(factory: _Callable[[], T], deps: list[_Any]) -> T:
+	"""Returns a memoized value.
+
+	Example:
+
+	```python
+	expensive = useMemo(lambda: compute_expensive(a, b), [a, b])
+	```
+	"""
+	...
+
+
+def useCallback(callback: T, deps: list[_Any]) -> T:
+	"""Returns a memoized callback.
+
+	Example:
+
+	```python
+	handle_click = useCallback(lambda e: print(e), [])
+	```
+	"""
+	...
+
+
+def useDeferredValue(value: T) -> T:
+	"""Defers updating a part of the UI. Returns a deferred version of the value."""
+	...
+
+
+def useTransition() -> tuple[bool, TransitionStartFunction]:
+	"""Returns a stateful value for pending state and a function to start transition.
+
+	Example:
+
+	```python
+	is_pending, start_transition = useTransition()
+	start_transition(lambda: set_state(new_value))
+	```
+	"""
+	...
+
+
+# =============================================================================
+# Context Hooks
+# =============================================================================
+
+
+def useContext(context: Context[T]) -> T:
+	"""Returns the current context value for the given context.
+
+	Example:
+
+	```python
+	theme = useContext(ThemeContext)
+	```
+	"""
+	...
+
+
+# =============================================================================
+# Other Hooks
+# =============================================================================
+
+
+def useId() -> str:
+	"""Generates a unique ID that is stable across server and client.
+
+	Example:
+
+	```python
+	id = useId()
+	# <label htmlFor={id}>Name</label>
+	# <input id={id} />
+	```
+	"""
+	...
+
+
+def useDebugValue(value: T, format_fn: _Callable[[T], _Any] | None = None) -> None:
+	"""Displays a label in React DevTools for custom hooks."""
+	...
+
+
+def useSyncExternalStore(
+	subscribe: _Callable[[_Callable[[], None]], _Callable[[], None]],
+	get_snapshot: _Callable[[], T],
+	get_server_snapshot: _Callable[[], T] | None = None,
+) -> T:
+	"""Subscribe to an external store.
+
+	Example:
+
+	```python
+	width = useSyncExternalStore(
+	    subscribe_to_resize,
+	    lambda: window.innerWidth
+	)
+	```
+	"""
+	...
+
+
+# =============================================================================
+# React Components and Elements
+# =============================================================================
+
+
+def createElement(
+	type: _Any,
+	props: dict[str, _Any] | None = None,
+	*children: _Any,
+) -> ReactElement:
+	"""Creates a React element."""
+	...
+
+
+def cloneElement(
+	element: ReactElement,
+	props: dict[str, _Any] | None = None,
+	*children: _Any,
+) -> ReactElement:
+	"""Clones and returns a new React element."""
+	...
+
+
+def isValidElement(obj: _Any) -> bool:
+	"""Checks if the object is a React element."""
+	...
+
+
+def memo(component: T, are_equal: _Callable[[_Any, _Any], bool] | None = None) -> T:
+	"""Memoizes a component to skip re-rendering when props are unchanged."""
+	...
+
+
+def forwardRef(
+	render: _Callable[[_Any, _Any], ReactElement | None],
+) -> _Callable[..., ReactElement | None]:
+	"""Lets your component expose a DOM node to a parent component with a ref."""
+	...
+
+
+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", 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):
+		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]:
+	"""Creates a Context object."""
+	...
+
+
+# =============================================================================
+# Components (stub declarations become Jsx-wrapped imports)
+# =============================================================================
+
+
+@_component
+def Suspense(
+	*, fallback: ReactNode | _PulseNode | None = None, name: str | None = None
+) -> ReactElement:
+	"""Lets you display a fallback while its children are loading."""
+	...
+
+
+# =============================================================================
+# Registration
+# =============================================================================
+
+# React is a namespace module where each hook is a named import
+JsModule.register(name="React", src="react", kind="namespace", values="named_import")

pulse/js/regexp.py

@@ -0,0 +1,57 @@
+"""
+JavaScript RegExp builtin module.
+
+Usage:
+
+```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
+
+
+class RegExp:
+	"""Class for JavaScript RegExp instances."""
+
+	def __init__(self, pattern: str, flags: str | None = None, /): ...
+
+	def exec(self, string: str) -> list[str] | None: ...
+	def test(self, string: str) -> bool: ...
+
+	@property
+	def source(self) -> str: ...
+
+	@property
+	def flags(self) -> str: ...
+
+	@property
+	def glob(self) -> bool: ...  # JavaScript 'global' property
+
+	@property
+	def ignoreCase(self) -> bool: ...
+
+	@property
+	def multiline(self) -> bool: ...
+
+	@property
+	def dotAll(self) -> bool: ...
+
+	@property
+	def unicode(self) -> bool: ...
+
+	@property
+	def sticky(self) -> bool: ...
+
+	@property
+	def lastIndex(self) -> int: ...
+
+	def toString(self) -> str: ...
+
+
+# Self-register this module as a JS builtin (global identifiers)
+JsModule.register(name=None)

pulse/js/set.py

@@ -0,0 +1,124 @@
+"""
+JavaScript Set builtin module.
+
+Usage:
+
+```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
+from collections.abc import Iterable as _Iterable
+from collections.abc import Iterator as _Iterator
+from typing import Any as _Any
+from typing import Generic as _Generic
+from typing import TypeVar as _TypeVar
+
+from pulse.transpiler.js_module import JsModule
+
+T = _TypeVar("T")
+
+
+class Set(_Generic[T]):
+	"""JavaScript Set - a collection of unique values.
+
+	Set[T] stores unique values of type T in insertion order.
+	"""
+
+	def __init__(self, iterable: _Iterable[T] | None = None, /) -> None: ...
+
+	@property
+	def size(self) -> int:
+		"""The number of values in the Set."""
+		...
+
+	def add(self, value: T) -> "Set[T]":
+		"""Add a value to the Set. Returns the Set for chaining."""
+		...
+
+	def clear(self) -> None:
+		"""Remove all values from the Set."""
+		...
+
+	def delete(self, value: T) -> bool:
+		"""Remove a value. Returns True if the value existed."""
+		...
+
+	def has(self, value: T) -> bool:
+		"""Return True if the value exists in the Set."""
+		...
+
+	def forEach(
+		self,
+		callback: _Callable[[T, T, "Set[T]"], None],
+		thisArg: _Any | None = None,
+		/,
+	) -> None:
+		"""Execute a function for each value.
+
+		Note: callback receives (value, value, set) for compatibility with Map.
+		"""
+		...
+
+	def keys(self) -> _Iterable[T]:
+		"""Return an iterator of values (same as values())."""
+		...
+
+	def values(self) -> _Iterable[T]:
+		"""Return an iterator of values."""
+		...
+
+	def entries(self) -> _Iterable[tuple[T, T]]:
+		"""Return an iterator of [value, value] pairs."""
+		...
+
+	def __iter__(self) -> _Iterator[T]:
+		"""Iterate over values."""
+		...
+
+	def __len__(self) -> int:
+		"""Return the number of values (same as size)."""
+		...
+
+	def __contains__(self, value: T) -> bool:
+		"""Check if value exists in the Set (same as has)."""
+		...
+
+	# ES2024 Set methods
+	def union(self, other: "Set[T]") -> "Set[T]":
+		"""Return a new Set with values from both sets (ES2024)."""
+		...
+
+	def intersection(self, other: "Set[T]") -> "Set[T]":
+		"""Return a new Set with values in both sets (ES2024)."""
+		...
+
+	def difference(self, other: "Set[T]") -> "Set[T]":
+		"""Return a new Set with values in this but not other (ES2024)."""
+		...
+
+	def symmetricDifference(self, other: "Set[T]") -> "Set[T]":
+		"""Return a new Set with values in either but not both (ES2024)."""
+		...
+
+	def isSubsetOf(self, other: "Set[T]") -> bool:
+		"""Return True if all values are in other (ES2024)."""
+		...
+
+	def isSupersetOf(self, other: "Set[T]") -> bool:
+		"""Return True if all values of other are in this (ES2024)."""
+		...
+
+	def isDisjointFrom(self, other: "Set[T]") -> bool:
+		"""Return True if no values are in common (ES2024)."""
+		...
+
+
+# Self-register this module as a JS builtin (global identifiers)
+JsModule.register(name=None)

pulse/js/string.py

@@ -0,0 +1,38 @@
+"""
+JavaScript String builtin module.
+
+Usage:
+
+```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
+
+from pulse.transpiler.js_module import JsModule
+
+
+class String:
+	"""JavaScript String constructor."""
+
+	def __init__(self, value: _Any) -> None: ...
+
+	@staticmethod
+	def fromCharCode(*codes: int) -> str: ...
+
+	@staticmethod
+	def fromCodePoint(*codePoints: int) -> str: ...
+
+	@staticmethod
+	def raw(template: str, *substitutions: str) -> str: ...
+
+
+# Self-register this module as a JS builtin (global identifier)
+JsModule.register(name=None)