pulse-framework 0.1.46__py3-none-any.whl → 0.1.47__py3-none-any.whl

pulse/js/_types.py

@@ -0,0 +1,297 @@
+"""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,253 @@
+"""
+JavaScript Array builtin module.
+
+Usage:
+    import pulse.js.array as Array
+    Array.isArray([1, 2, 3])      # -> Array.isArray([1, 2, 3])
+    Array.from([1, 2, 3])         # -> Array.from([1, 2, 3])
+
+    # Note: For 'from' (Python keyword), use namespace import:
+    # import pulse.js.array as Array; Array.from(...)
+    # Or use the underscore version for direct import:
+    from pulse.js.array import isArray, from_
+    isArray([1, 2, 3])            # -> Array.isArray([1, 2, 3])
+    from_([1, 2, 3])              # -> Array.from([1, 2, 3])
+"""
+
+from collections.abc import Callable as _Callable
+from collections.abc import Iterable as _Iterable
+from typing import Any as _Any
+from typing import Generic as _Generic
+from typing import TypeVar as _TypeVar
+
+from pulse.transpiler.js_module import register_js_module as _register_js_module
+
+T = _TypeVar("T")
+U = _TypeVar("U")
+S = _TypeVar("S")
+
+
+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.
+	"""
+
+	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
+	def isArray(value: _Any) -> bool:
+		"""Determine whether the passed value is an Array."""
+		...
+
+	@staticmethod
+	def from_(
+		arrayLike: _Iterable[T],
+		mapFn: _Callable[[T, int], U] | None = None,
+		thisArg: _Any | None = None,
+	) -> "list[U] | list[T]":
+		"""Create a new Array from an array-like or iterable object."""
+		...
+
+	@staticmethod
+	def of(*elements: T) -> "list[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
+	) -> "list[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]") -> "list[T]":
+		"""Merge arrays and/or values into a new array."""
+		...
+
+	def slice(self, start: int = 0, end: int | None = None) -> "list[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) -> "list[_Any]":
+		"""Flatten nested arrays to the specified depth."""
+		...
+
+	def flatMap(
+		self, callback: _Callable[[T, int, "Array[T]"], _Iterable[U]]
+	) -> "list[U]":
+		"""Map then flatten the result by one level."""
+		...
+
+	def toReversed(self) -> "list[T]":
+		"""Return a new reversed array (ES2023)."""
+		...
+
+	def toSorted(self, compareFn: _Callable[[T, T], int] | None = None) -> "list[T]":
+		"""Return a new sorted array (ES2023)."""
+		...
+
+	def toSpliced(
+		self, start: int, deleteCount: int | None = None, *items: T
+	) -> "list[T]":
+		"""Return a new array with elements spliced (ES2023)."""
+		...
+
+	def with_(self, index: int, value: T) -> "list[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]) -> "list[U]":
+		"""Create a new array with results of calling callback on each element."""
+		...
+
+	def filter(self, callback: _Callable[[T, int, "Array[T]"], bool]) -> "list[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."""
+		...
+
+
+# Self-register this module as a JS builtin
+_register_js_module(name="Array", global_scope=True)

pulse/js/console.py

@@ -0,0 +1,47 @@
+"""
+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")
+"""
+
+from typing import Any as _Any
+
+from pulse.transpiler.js_module import register_js_module as _register_js_module
+
+
+# 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
+_register_js_module(name="console")

pulse/js/date.py

@@ -0,0 +1,113 @@
+"""
+JavaScript Date builtin module.
+
+Usage:
+    import pulse.js.date as Date
+    Date.now()                    # -> Date.now()
+    Date.parse("2023-01-01")      # -> Date.parse("2023-01-01")
+
+    from pulse.js.date import now, parse
+    now()                         # -> Date.now()
+    parse("2023-01-01")           # -> Date.parse("2023-01-01")
+"""
+
+from typing import Any as _Any
+
+from pulse.transpiler.js_module import register_js_module as _register_js_module
+
+
+class Date:
+	"""Class for JavaScript Date instances."""
+
+	def __init__(self, value: int | str | None = None): ...
+
+	@staticmethod
+	def now() -> float: ...
+
+	@staticmethod
+	def parse(dateString: str) -> float: ...
+
+	@staticmethod
+	def UTC(
+		year: int,
+		month: int,
+		date: int | None = None,
+		hours: int | None = None,
+		minutes: int | None = None,
+		seconds: int | None = None,
+		ms: int | None = None,
+	) -> float: ...
+
+	def getDate(self) -> int: ...
+	def getDay(self) -> int: ...
+	def getFullYear(self) -> int: ...
+	def getHours(self) -> int: ...
+	def getMilliseconds(self) -> int: ...
+	def getMinutes(self) -> int: ...
+	def getMonth(self) -> int: ...
+	def getSeconds(self) -> int: ...
+	def getTime(self) -> float: ...
+	def getTimezoneOffset(self) -> int: ...
+	def getUTCDate(self) -> int: ...
+	def getUTCDay(self) -> int: ...
+	def getUTCFullYear(self) -> int: ...
+	def getUTCHours(self) -> int: ...
+	def getUTCMilliseconds(self) -> int: ...
+	def getUTCMinutes(self) -> int: ...
+	def getUTCMonth(self) -> int: ...
+	def getUTCSeconds(self) -> int: ...
+	def setDate(self, date: int) -> float: ...
+	def setFullYear(
+		self, year: int, month: int | None = None, date: int | None = None
+	) -> float: ...
+	def setHours(
+		self,
+		hours: int,
+		min: int | None = None,
+		sec: int | None = None,
+		ms: int | None = None,
+	) -> float: ...
+	def setMilliseconds(self, ms: int) -> float: ...
+	def setMinutes(
+		self, min: int, sec: int | None = None, ms: int | None = None
+	) -> float: ...
+	def setMonth(self, month: int, date: int | None = None) -> float: ...
+	def setSeconds(self, sec: int, ms: int | None = None) -> float: ...
+	def setTime(self, time: float) -> float: ...
+	def setUTCDate(self, date: int) -> float: ...
+	def setUTCFullYear(
+		self, year: int, month: int | None = None, date: int | None = None
+	) -> float: ...
+	def setUTCHours(
+		self,
+		hours: int,
+		min: int | None = None,
+		sec: int | None = None,
+		ms: int | None = None,
+	) -> float: ...
+	def setUTCMilliseconds(self, ms: int) -> float: ...
+	def setUTCMinutes(
+		self, min: int, sec: int | None = None, ms: int | None = None
+	) -> float: ...
+	def setUTCMonth(self, month: int, date: int | None = None) -> float: ...
+	def setUTCSeconds(self, sec: int, ms: int | None = None) -> float: ...
+	def toDateString(self) -> str: ...
+	def toISOString(self) -> str: ...
+	def toJSON(self, key: _Any | None = None) -> str: ...
+	def toLocaleDateString(
+		self, locales: str | None = None, options: _Any | None = None
+	) -> str: ...
+	def toLocaleString(
+		self, locales: str | None = None, options: _Any | None = None
+	) -> str: ...
+	def toLocaleTimeString(
+		self, locales: str | None = None, options: _Any | None = None
+	) -> str: ...
+	def toString(self) -> str: ...
+	def toTimeString(self) -> str: ...
+	def toUTCString(self) -> str: ...
+	def valueOf(self) -> float: ...
+
+
+# Self-register this module as a JS builtin
+_register_js_module(name="Date", global_scope=True)