pulse-framework 0.1.62__py3-none-any.whl

pulse/js/_types.py

@@ -0,0 +1,299 @@
+"""Common type definitions for JavaScript builtin bindings.
+
+This module provides type aliases and protocols for proper typing of JS APIs.
+These are purely for static type checking - they have no runtime effect.
+"""
+
+from collections.abc import Awaitable as _Awaitable
+from collections.abc import Callable as _Callable
+from collections.abc import Iterator as _Iterator
+from typing import Protocol as _Protocol
+from typing import TypeVar as _TypeVar
+from typing import overload as _overload
+
+# Type variables
+T = _TypeVar("T")
+T_co = _TypeVar("T_co", covariant=True)
+T_contra = _TypeVar("T_contra", contravariant=True)
+K = _TypeVar("K")
+V = _TypeVar("V")
+R = _TypeVar("R")
+
+# Promise result types
+PromiseSettledResult = dict[
+	str, T | str
+]  # { status: "fulfilled" | "rejected", value?: T, reason?: any }
+
+
+# Callback type aliases for collection methods
+# These mirror JavaScript's callback signatures
+
+# Array callbacks
+ArrayCallback = _Callable[[T, int, "JSArray[T]"], R]
+ArrayCallbackNoIndex = _Callable[[T], R]
+ArrayPredicate = _Callable[[T, int, "JSArray[T]"], bool]
+ArrayReducer = _Callable[[R, T, int, "JSArray[T]"], R]
+ArrayComparator = _Callable[[T, T], int]
+
+# Map callbacks
+MapForEachCallback = _Callable[[V, K, "JSMap[K, V]"], None]
+
+# Set callbacks
+SetForEachCallback = _Callable[[T, T, "JSSet[T]"], None]
+
+
+# JavaScript Iterator protocol
+class JSIterator(_Protocol[T_co]):
+	"""Protocol for JavaScript Iterator objects."""
+
+	def next(self) -> "JSIteratorResult[T_co]": ...
+
+	def __iter__(self) -> "JSIterator[T_co]": ...
+
+
+class JSIteratorResult(_Protocol[T_co]):
+	"""Result from JavaScript Iterator.next()."""
+
+	@property
+	def value(self) -> T_co: ...
+
+	@property
+	def done(self) -> bool: ...
+
+
+# JavaScript Iterable protocol
+class JSIterable(_Protocol[T_co]):
+	"""Protocol for JavaScript Iterable objects (has Symbol.iterator)."""
+
+	def __iter__(self) -> _Iterator[T_co]: ...
+
+
+# Placeholder for forward references within this module
+class JSArray(_Protocol[T_co]):
+	"""Forward reference for Array type - actual implementation in array.py."""
+
+	...
+
+
+V_co = _TypeVar("V_co", covariant=True)
+
+
+class JSMap(_Protocol[T_co, V_co]):
+	"""Forward reference for Map type - actual implementation in map.py."""
+
+	...
+
+
+class JSSet(_Protocol[T_co]):
+	"""Forward reference for Set type - actual implementation in set.py."""
+
+	...
+
+
+# DOM Element types (for document/window methods)
+class Element(_Protocol):
+	"""Protocol for DOM Element objects."""
+
+	@property
+	def tagName(self) -> str: ...
+
+	@property
+	def id(self) -> str: ...
+
+	@property
+	def className(self) -> str: ...
+
+	@property
+	def innerHTML(self) -> str: ...
+
+	@property
+	def textContent(self) -> str | None: ...
+
+	@property
+	def parentElement(self) -> "Element | None": ...
+
+	@property
+	def children(self) -> "NodeList[Element]": ...
+
+	def querySelector(self, selectors: str) -> "Element | None": ...
+	def querySelectorAll(self, selectors: str) -> "NodeList[Element]": ...
+	def getAttribute(self, name: str) -> str | None: ...
+	def setAttribute(self, name: str, value: str) -> None: ...
+	def removeAttribute(self, name: str) -> None: ...
+	def hasAttribute(self, name: str) -> bool: ...
+	def addEventListener(
+		self,
+		type: str,
+		listener: _Callable[..., None],
+		options: bool | dict[str, bool] | None = None,
+		/,
+	) -> None: ...
+	def removeEventListener(
+		self,
+		type: str,
+		listener: _Callable[..., None],
+		options: bool | dict[str, bool] | None = None,
+		/,
+	) -> None: ...
+	def remove(self) -> None: ...
+	def append(self, *nodes: "Element | str") -> None: ...
+	def prepend(self, *nodes: "Element | str") -> None: ...
+	def replaceWith(self, *nodes: "Element | str") -> None: ...
+
+
+class HTMLElement(Element, _Protocol):
+	"""Protocol for HTMLElement objects."""
+
+	@property
+	def style(self) -> "CSSStyleDeclaration": ...
+
+	@property
+	def dataset(self) -> dict[str, str]: ...
+
+	@property
+	def offsetWidth(self) -> int: ...
+
+	@property
+	def offsetHeight(self) -> int: ...
+
+	def focus(self) -> None: ...
+	def blur(self) -> None: ...
+	def click(self) -> None: ...
+
+
+class CSSStyleDeclaration(_Protocol):
+	"""Protocol for CSSStyleDeclaration."""
+
+	def getPropertyValue(self, property: str) -> str: ...
+	def setProperty(self, property: str, value: str, priority: str = "", /) -> None: ...
+	def removeProperty(self, property: str) -> str: ...
+
+
+class NodeList(_Protocol[T]):
+	"""Protocol for NodeList objects."""
+
+	@property
+	def length(self) -> int: ...
+
+	def item(self, index: int) -> T | None: ...
+	def __iter__(self) -> _Iterator[T]: ...
+	def __len__(self) -> int: ...
+
+	@_overload
+	def __getitem__(self, index: int) -> T: ...
+	@_overload
+	def __getitem__(self, index: slice) -> list[T]: ...
+
+
+class HTMLCollection(_Protocol[T_co]):
+	"""Protocol for HTMLCollection objects."""
+
+	@property
+	def length(self) -> int: ...
+
+	def item(self, index: int) -> T_co | None: ...
+	def namedItem(self, name: str) -> T_co | None: ...
+	def __iter__(self) -> _Iterator[T_co]: ...
+	def __len__(self) -> int: ...
+
+
+# Selection API
+class Selection(_Protocol):
+	"""Protocol for window.getSelection() result."""
+
+	@property
+	def anchorNode(self) -> Element | None: ...
+
+	@property
+	def focusNode(self) -> Element | None: ...
+
+	@property
+	def isCollapsed(self) -> bool: ...
+
+	@property
+	def rangeCount(self) -> int: ...
+
+	def getRangeAt(self, index: int) -> "Range": ...
+	def collapse(self, node: Element | None, offset: int = 0, /) -> None: ...
+	def selectAllChildren(self, node: Element) -> None: ...
+	def removeAllRanges(self) -> None: ...
+	def toString(self) -> str: ...
+
+
+class Range(_Protocol):
+	"""Protocol for Range objects."""
+
+	@property
+	def startContainer(self) -> Element: ...
+
+	@property
+	def endContainer(self) -> Element: ...
+
+	@property
+	def startOffset(self) -> int: ...
+
+	@property
+	def endOffset(self) -> int: ...
+
+	@property
+	def collapsed(self) -> bool: ...
+
+	def setStart(self, node: Element, offset: int) -> None: ...
+	def setEnd(self, node: Element, offset: int) -> None: ...
+	def selectNode(self, node: Element) -> None: ...
+	def selectNodeContents(self, node: Element) -> None: ...
+	def collapse(self, toStart: bool = False, /) -> None: ...
+	def cloneContents(self) -> Element: ...
+	def deleteContents(self) -> None: ...
+
+
+# Clipboard API
+class Clipboard(_Protocol):
+	"""Protocol for Navigator.clipboard."""
+
+	def read(self) -> _Awaitable[list["ClipboardItem"]]: ...
+	def readText(self) -> _Awaitable[str]: ...
+	def write(self, data: list["ClipboardItem"]) -> _Awaitable[None]: ...
+	def writeText(self, text: str) -> _Awaitable[None]: ...
+
+
+class ClipboardItem(_Protocol):
+	"""Protocol for ClipboardItem."""
+
+	@property
+	def types(self) -> list[str]: ...
+
+	def getType(self, type: str) -> _Awaitable[bytes]: ...
+
+
+# Event types
+class Event(_Protocol):
+	"""Protocol for Event objects."""
+
+	@property
+	def type(self) -> str: ...
+
+	@property
+	def target(self) -> Element | None: ...
+
+	@property
+	def currentTarget(self) -> Element | None: ...
+
+	@property
+	def bubbles(self) -> bool: ...
+
+	@property
+	def cancelable(self) -> bool: ...
+
+	@property
+	def defaultPrevented(self) -> bool: ...
+
+	def preventDefault(self) -> None: ...
+	def stopPropagation(self) -> None: ...
+	def stopImmediatePropagation(self) -> None: ...
+
+
+# JSON types
+JSONValue = None | bool | int | float | str | list["JSONValue"] | dict[str, "JSONValue"]
+JSONReplacer = list[str | int] | _Callable[[str, JSONValue], JSONValue]
+JSONReviver = _Callable[[str, JSONValue], JSONValue]

pulse/js/array.py

@@ -0,0 +1,339 @@
+"""
+JavaScript Array builtin module.
+
+Usage:
+
+```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
+
+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 TypeGuard as _TypeGuard
+from typing import TypeVar as _TypeVar
+from typing import overload as _overload
+
+from pulse.transpiler.js_module import JsModule
+
+T = _TypeVar("T")
+U = _TypeVar("U")
+# TypeVars for static methods (can't use class-level T)
+_T = _TypeVar("_T")
+_U = _TypeVar("_U")
+
+
+class Array(_Generic[T]):
+	"""JavaScript Array - a generic indexed collection.
+
+	Array[T] represents a JavaScript array containing elements of type T.
+	All instance methods preserve the expected generic types.
+	"""
+
+	@_overload
+	def __init__(self) -> None:
+		"""Create an empty Array."""
+		...
+
+	@_overload
+	def __init__(self, length: int, /) -> None:
+		"""Create an Array with the specified length."""
+		...
+
+	@_overload
+	def __init__(self, *elements: T) -> None:
+		"""Create an Array with the given elements."""
+		...
+
+	def __init__(self, *args: T | int) -> None:
+		"""Create an Array.
+
+		- No arguments: empty array
+		- Single int: array with that length
+		- Multiple args: array with those elements
+		"""
+		...
+
+	# Static methods
+	@staticmethod
+	@_overload
+	def isArray(value: list[_T], /) -> _TypeGuard["Array[_T]"]:
+		"""Determine whether the passed value is an Array."""
+		...
+
+	@staticmethod
+	@_overload
+	def isArray(value: "Array[_T]", /) -> _TypeGuard["Array[_T]"]:
+		"""Determine whether the passed value is an Array."""
+		...
+
+	@staticmethod
+	@_overload
+	def isArray(value: _Any, /) -> _TypeGuard["Array[_Any]"]:
+		"""Determine whether the passed value is an Array."""
+		...
+
+	@staticmethod
+	def isArray(value: _Any, /) -> _TypeGuard["Array[_Any]"]:
+		"""Determine whether the passed value is an Array."""
+		...
+
+	@staticmethod
+	@_overload
+	def from_(
+		arrayLike: _Iterable[_T] | "Array[_T]",
+		/,
+	) -> "Array[_T]":
+		"""Create a new Array from an array-like or iterable object."""
+		...
+
+	@staticmethod
+	@_overload
+	def from_(
+		arrayLike: _Iterable[_T] | "Array[_T]",
+		mapFn: _Callable[[_T, int], _U],
+		thisArg: _Any | None = None,
+		/,
+	) -> "Array[_U]":
+		"""Create a new Array from an array-like or iterable object, mapping each element."""
+		...
+
+	@staticmethod
+	def from_(
+		arrayLike: _Iterable[_T] | "Array[_T]",
+		mapFn: _Callable[[_T, int], _U] | None = None,
+		thisArg: _Any | None = None,
+		/,
+	) -> "Array[_U] | Array[_T]":
+		"""Create a new Array from an array-like or iterable object."""
+		...
+
+	@staticmethod
+	def of(*elements: _T) -> "Array[_T]":
+		"""Create a new Array from a variable number of arguments."""
+		...
+
+	# Accessor properties
+	@property
+	def length(self) -> int:
+		"""The number of elements in the array."""
+		...
+
+	# Mutator methods (modify the array in place)
+	def push(self, *items: T) -> int:
+		"""Add elements to the end; returns new length."""
+		...
+
+	def pop(self) -> T | None:
+		"""Remove and return the last element."""
+		...
+
+	def shift(self) -> T | None:
+		"""Remove and return the first element."""
+		...
+
+	def unshift(self, *items: T) -> int:
+		"""Add elements to the beginning; returns new length."""
+		...
+
+	def splice(
+		self, start: int, deleteCount: int | None = None, /, *items: T
+	) -> "Array[T]":
+		"""Remove/replace elements and optionally insert new ones."""
+		...
+
+	def reverse(self) -> "Array[T]":
+		"""Reverse the array in place."""
+		...
+
+	def sort(self, compareFn: _Callable[[T, T], int] | None = None, /) -> "Array[T]":
+		"""Sort the array in place."""
+		...
+
+	def fill(self, value: T, start: int = 0, end: int | None = None, /) -> "Array[T]":
+		"""Fill all elements with a static value."""
+		...
+
+	def copyWithin(
+		self, target: int, start: int = 0, end: int | None = None, /
+	) -> "Array[T]":
+		"""Copy part of the array to another location within it."""
+		...
+
+	# Accessor methods (return new arrays or values)
+	def concat(self, *items: T | "_Iterable[T]") -> "Array[T]":
+		"""Merge arrays and/or values into a new array."""
+		...
+
+	def slice(self, start: int = 0, end: int | None = None, /) -> "Array[T]":
+		"""Return a shallow copy of a portion of the array."""
+		...
+
+	def join(self, separator: str = ",", /) -> str:
+		"""Join all elements into a string."""
+		...
+
+	def indexOf(self, searchElement: T, fromIndex: int = 0, /) -> int:
+		"""Return first index of element, or -1 if not found."""
+		...
+
+	def lastIndexOf(self, searchElement: T, fromIndex: int | None = None, /) -> int:
+		"""Return last index of element, or -1 if not found."""
+		...
+
+	def includes(self, searchElement: T, fromIndex: int = 0, /) -> bool:
+		"""Determine whether the array contains the element."""
+		...
+
+	def at(self, index: int) -> T | None:
+		"""Return element at index (supports negative indexing)."""
+		...
+
+	def flat(self, depth: int = 1, /) -> "Array[_Any]":
+		"""Flatten nested arrays to the specified depth."""
+		...
+
+	def flatMap(
+		self, callback: _Callable[[T, int, "Array[T]"], _Iterable[U]]
+	) -> "Array[U]":
+		"""Map then flatten the result by one level."""
+		...
+
+	def toReversed(self) -> "Array[T]":
+		"""Return a new reversed array (ES2023)."""
+		...
+
+	def toSorted(
+		self, compareFn: _Callable[[T, T], int] | None = None, /
+	) -> "Array[T]":
+		"""Return a new sorted array (ES2023)."""
+		...
+
+	def toSpliced(
+		self, start: int, deleteCount: int | None = None, /, *items: T
+	) -> "Array[T]":
+		"""Return a new array with elements spliced (ES2023)."""
+		...
+
+	def with_(self, index: int, value: T) -> "Array[T]":
+		"""Return a new array with element at index replaced (ES2023)."""
+		...
+
+	# Iteration methods
+	def forEach(self, callback: _Callable[[T, int, "Array[T]"], None]) -> None:
+		"""Execute a function for each element."""
+		...
+
+	def map(self, callback: _Callable[[T, int, "Array[T]"], U]) -> "Array[U]":
+		"""Create a new array with results of calling callback on each element."""
+		...
+
+	def filter(self, callback: _Callable[[T, int, "Array[T]"], bool]) -> "Array[T]":
+		"""Create a new array with elements that pass the test."""
+		...
+
+	def reduce(
+		self,
+		callback: _Callable[[U, T, int, "Array[T]"], U],
+		initialValue: U | None = None,
+		/,
+	) -> U:
+		"""Reduce array to a single value (left to right).
+
+		If no initialValue is provided, the first element is used.
+		"""
+		...
+
+	def reduceRight(
+		self,
+		callback: _Callable[[U, T, int, "Array[T]"], U],
+		initialValue: U | None = None,
+		/,
+	) -> U:
+		"""Reduce array to a single value (right to left).
+
+		If no initialValue is provided, the last element is used.
+		"""
+		...
+
+	def find(self, callback: _Callable[[T, int, "Array[T]"], bool]) -> T | None:
+		"""Return first element satisfying the callback."""
+		...
+
+	def findIndex(self, callback: _Callable[[T, int, "Array[T]"], bool]) -> int:
+		"""Return index of first element satisfying the callback, or -1."""
+		...
+
+	def findLast(self, callback: _Callable[[T, int, "Array[T]"], bool]) -> T | None:
+		"""Return last element satisfying the callback (ES2023)."""
+		...
+
+	def findLastIndex(self, callback: _Callable[[T, int, "Array[T]"], bool]) -> int:
+		"""Return index of last element satisfying the callback, or -1 (ES2023)."""
+		...
+
+	def every(self, callback: _Callable[[T, int, "Array[T]"], bool]) -> bool:
+		"""Test whether all elements pass the callback."""
+		...
+
+	def some(self, callback: _Callable[[T, int, "Array[T]"], bool]) -> bool:
+		"""Test whether at least one element passes the callback."""
+		...
+
+	# Iterator methods
+	def keys(self) -> _Iterable[int]:
+		"""Return an iterator of array indices."""
+		...
+
+	def values(self) -> _Iterable[T]:
+		"""Return an iterator of array values."""
+		...
+
+	def entries(self) -> _Iterable[tuple[int, T]]:
+		"""Return an iterator of [index, value] pairs."""
+		...
+
+	# String conversion
+	def toString(self) -> str:
+		"""Return a string representing the array."""
+		...
+
+	def toLocaleString(self) -> str:
+		"""Return a localized string representing the array."""
+		...
+
+	# Python protocol methods
+	def __iter__(self) -> _Iterator[T]:
+		"""Iterate over array elements."""
+		...
+
+	def __getitem__(self, index: int) -> T:
+		"""Get element at index."""
+		...
+
+	def __setitem__(self, index: int, value: T) -> None:
+		"""Set element at index."""
+		...
+
+	def __len__(self) -> int:
+		"""Return the number of elements (same as length)."""
+		...
+
+	def __contains__(self, value: T) -> bool:
+		"""Check if value exists in the array (same as includes)."""
+		...
+
+
+# Self-register this module as a JS builtin (global identifier)
+JsModule.register(name=None)

pulse/js/console.py

@@ -0,0 +1,50 @@
+"""
+JavaScript Console builtin module.
+
+Usage:
+
+```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
+
+from pulse.transpiler.js_module import JsModule
+
+
+# Methods (type stubs for IDE support)
+def assert_(condition: bool, *data: _Any) -> None: ...
+def clear() -> None: ...
+def count(label: str | None = None, /) -> None: ...
+def countReset(label: str | None = None, /) -> None: ...
+def debug(*data: _Any) -> None: ...
+def dir(item: _Any, options: dict[str, _Any] | None = None, /) -> None: ...
+def dirxml(*data: _Any) -> None: ...
+def error(*data: _Any) -> None: ...
+def group(*label: _Any) -> None: ...
+def groupCollapsed(*label: _Any) -> None: ...
+def groupEnd() -> None: ...
+def info(*data: _Any) -> None: ...
+def log(*data: _Any) -> None: ...
+def table(tabularData: _Any, properties: list[str] | None = None, /) -> None: ...
+def time(label: str | None = None, /) -> None: ...
+def timeEnd(label: str | None = None, /) -> None: ...
+def timeLog(label: str | None = None, /, *data: _Any) -> None: ...
+def trace(*data: _Any) -> None: ...
+def warn(*data: _Any) -> None: ...
+
+
+# Self-register this module as a JS builtin
+JsModule.register(name="console")