pulse-framework 0.1.62__py3-none-any.whl

pulse/codegen/templates/route.py

@@ -0,0 +1,345 @@
+"""Route code generation using transpiler."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from pulse.transpiler import (
+	Constant,
+	Import,
+	collect_function_graph,
+	emit,
+	get_registered_imports,
+	registered_constants,
+	registered_functions,
+)
+from pulse.transpiler.emit_context import EmitContext
+from pulse.transpiler.function import AnyJsFunction
+
+
+def _get_import_src(imp: Import) -> str:
+	"""Get the import source path, remapping to asset path for local imports."""
+	if imp.asset:
+		return imp.asset.import_path()
+	return imp.src
+
+
+def _generate_import_statement(
+	src: str,
+	imports: list[Import],
+) -> str:
+	"""Generate import statement(s) for a source module.
+
+	Args:
+		src: The original source path (may be remapped for local imports)
+		imports: List of Import objects for this source
+	"""
+	default_imports: list[Import] = []
+	namespace_imports: list[Import] = []
+	named_imports: list[Import] = []
+	type_imports: list[Import] = []
+	has_side_effect = False
+
+	for imp in imports:
+		if imp.is_side_effect:
+			has_side_effect = True
+		elif imp.is_namespace:
+			namespace_imports.append(imp)
+		elif imp.is_default:
+			if imp.is_type:
+				type_imports.append(imp)
+			else:
+				default_imports.append(imp)
+		else:
+			if imp.is_type:
+				type_imports.append(imp)
+			else:
+				named_imports.append(imp)
+
+	# Remap source path if this is a local import
+	import_src = src
+	for imp in imports:
+		if imp.asset:
+			import_src = imp.asset.import_path()
+			break
+
+	lines: list[str] = []
+
+	# Namespace import (only one allowed per source)
+	if namespace_imports:
+		imp = namespace_imports[0]
+		lines.append(f'import * as {imp.js_name} from "{import_src}";')
+
+	# Default import (only one allowed per source)
+	if default_imports:
+		imp = default_imports[0]
+		lines.append(f'import {imp.js_name} from "{import_src}";')
+
+	# Named imports
+	if named_imports:
+		members = [f"{imp.name} as {imp.js_name}" for imp in named_imports]
+		lines.append(f'import {{ {", ".join(members)} }} from "{import_src}";')
+
+	# Type imports
+	if type_imports:
+		type_members: list[str] = []
+		for imp in type_imports:
+			if imp.is_default:
+				type_members.append(f"default as {imp.js_name}")
+			else:
+				type_members.append(f"{imp.name} as {imp.js_name}")
+		lines.append(
+			f'import type {{ {", ".join(type_members)} }} from "{import_src}";'
+		)
+
+	# Side-effect only import (only if no other imports)
+	if (
+		has_side_effect
+		and not default_imports
+		and not namespace_imports
+		and not named_imports
+		and not type_imports
+	):
+		lines.append(f'import "{import_src}";')
+
+	return "\n".join(lines)
+
+
+def _generate_imports_section(imports: Sequence[Import]) -> str:
+	"""Generate the full imports section with deduplication and topological ordering.
+
+	Args:
+		imports: List of Import objects to generate (should be eager imports only)
+	"""
+	if not imports:
+		return ""
+
+	# Deduplicate imports by ID
+	seen_ids: set[str] = set()
+	unique_imports: list[Import] = []
+	for imp in imports:
+		if imp.id not in seen_ids:
+			seen_ids.add(imp.id)
+			unique_imports.append(imp)
+
+	# Group by source
+	grouped: dict[str, list[Import]] = {}
+	for imp in unique_imports:
+		if imp.src not in grouped:
+			grouped[imp.src] = []
+		grouped[imp.src].append(imp)
+
+	# Topological sort using Import.before constraints (Kahn's algorithm)
+	keys = list(grouped.keys())
+	if not keys:
+		return ""
+
+	index = {k: i for i, k in enumerate(keys)}  # for stability
+	indegree: dict[str, int] = {k: 0 for k in keys}
+	adj: dict[str, list[str]] = {k: [] for k in keys}
+
+	for src, src_imports in grouped.items():
+		for imp in src_imports:
+			for before_src in imp.before:
+				if before_src in adj:
+					adj[src].append(before_src)
+					indegree[before_src] += 1
+
+	queue = [k for k, d in indegree.items() if d == 0]
+	queue.sort(key=lambda k: index[k])
+	ordered: list[str] = []
+
+	while queue:
+		u = queue.pop(0)
+		ordered.append(u)
+		for v in adj[u]:
+			indegree[v] -= 1
+			if indegree[v] == 0:
+				queue.append(v)
+				queue.sort(key=lambda k: index[k])
+
+	# Fall back to insertion order if cycle detected
+	if len(ordered) != len(keys):
+		ordered = keys
+
+	lines: list[str] = []
+	for src in ordered:
+		stmt = _generate_import_statement(src, grouped[src])
+		if stmt:
+			lines.append(stmt)
+
+	return "\n".join(lines)
+
+
+def _generate_lazy_imports_section(imports: Sequence[Import]) -> str:
+	"""Generate lazy import factories for code-splitting.
+
+	Lazy imports are emitted as factory functions compatible with React.lazy.
+	React.lazy requires factories that return { default: Component }.
+
+	For default imports: () => import("./Chart")
+	For named imports: () => import("./Chart").then(m => ({ default: m.LineChart }))
+
+	Args:
+		imports: List of lazy Import objects
+	"""
+	if not imports:
+		return ""
+
+	lines: list[str] = ["// Lazy imports"]
+	for imp in imports:
+		import_src = _get_import_src(imp)
+
+		if imp.is_default or imp.is_namespace:
+			# Default/namespace: () => import("module") - already has { default }
+			factory = f'() => import("{import_src}")'
+		else:
+			# Named: wrap in { default } for React.lazy compatibility
+			factory = (
+				f'() => import("{import_src}").then(m => ({{ default: m.{imp.name} }}))'
+			)
+
+		lines.append(f"const {imp.js_name} = {factory};")
+
+	return "\n".join(lines)
+
+
+def _generate_constants_section(constants: Sequence[Constant]) -> str:
+	"""Generate the constants section."""
+	if not constants:
+		return ""
+
+	lines: list[str] = ["// Constants"]
+	for const in constants:
+		js_value = emit(const.expr)
+		lines.append(f"const {const.js_name} = {js_value};")
+
+	return "\n".join(lines)
+
+
+def _generate_functions_section(functions: Sequence[AnyJsFunction]) -> str:
+	"""Generate the functions section with actual transpiled code."""
+	if not functions:
+		return ""
+
+	lines: list[str] = ["// Functions"]
+	for fn in functions:
+		js_code = emit(fn.transpile())
+		lines.append(js_code)
+
+	return "\n".join(lines)
+
+
+def _generate_registry_section(
+	imports: Sequence[Import],
+	constants: Sequence[Constant],
+	functions: Sequence[AnyJsFunction],
+) -> str:
+	"""Generate the unified registry from all registered entities.
+
+	The registry contains all values that need to be looked up at runtime,
+	keyed by their unique ID.
+	"""
+	lines: list[str] = []
+	lines.append("// Unified Registry")
+	lines.append("const __registry = {")
+
+	# Add imports
+	for imp in imports:
+		if not imp.is_side_effect:
+			lines.append(f'  "{imp.id}": {imp.js_name},')
+
+	# Add constants
+	for const in constants:
+		lines.append(f'  "{const.id}": {const.js_name},')
+
+	# Add functions
+	for fn in functions:
+		lines.append(f'  "{fn.id}": {fn.js_name},')
+
+	lines.append("};")
+
+	return "\n".join(lines)
+
+
+def generate_route(
+	path: str,
+	route_file_path: str,
+) -> str:
+	"""Generate a route file with all registered imports, functions, and components.
+
+	Args:
+		path: The route path (e.g., "/users/:id")
+		route_file_path: Path from pulse root (e.g., "routes/users/index.tsx")
+	"""
+	with EmitContext(route_file_path=route_file_path):
+		# Add core Pulse imports
+		pulse_view_import = Import("PulseView", "pulse-ui-client")
+
+		# Collect function graph (constants + functions in dependency order)
+		fn_constants, funcs = collect_function_graph(registered_functions())
+
+		# Include all registered constants (not just function dependencies)
+		# This ensures constants used as component tags are included
+		fn_const_ids = {c.id for c in fn_constants}
+		all_constants = list(fn_constants)
+		for const in registered_constants():
+			if const.id not in fn_const_ids:
+				all_constants.append(const)
+		constants = all_constants
+
+		# Get all registered imports and split by lazy flag
+		all_imports = list(get_registered_imports())
+		eager_imports = [imp for imp in all_imports if not imp.lazy]
+		lazy_imports = [imp for imp in all_imports if imp.lazy]
+
+		# Generate output sections
+		output_parts: list[str] = []
+
+		# Eager imports (ES6 import statements)
+		imports_section = _generate_imports_section(eager_imports)
+		if imports_section:
+			output_parts.append(imports_section)
+
+		output_parts.append("")
+
+		# Lazy imports (factory functions)
+		lazy_section = _generate_lazy_imports_section(lazy_imports)
+		if lazy_section:
+			output_parts.append(lazy_section)
+			output_parts.append("")
+
+		if constants:
+			output_parts.append(_generate_constants_section(constants))
+			output_parts.append("")
+
+		if funcs:
+			output_parts.append(_generate_functions_section(funcs))
+			output_parts.append("")
+
+		# Generate the unified registry including all imports, constants and functions
+		output_parts.append(_generate_registry_section(all_imports, constants, funcs))
+		output_parts.append("")
+
+		# Route component
+		pulse_view_js = pulse_view_import.js_name
+		output_parts.append(f'''const path = "{path}";
+
+export default function RouteComponent() {{
+  return (
+    <{pulse_view_js} key={{path}} registry={{__registry}} path={{path}} />
+  );
+}}''')
+		output_parts.append("")
+
+		# Headers function
+		output_parts.append("""// Action and loader headers are not returned automatically
+function hasAnyHeaders(headers) {
+  return [...headers].length > 0;
+}
+
+export function headers({ actionHeaders, loaderHeaders }) {
+  return hasAnyHeaders(actionHeaders) ? actionHeaders : loaderHeaders;
+}""")
+
+		return "\n".join(output_parts)

pulse/codegen/templates/routes_ts.py

@@ -0,0 +1,42 @@
+from mako.template import Template
+
+# Mako template for routes configuration
+ROUTES_CONFIG_TEMPLATE = Template(
+	"""import {
+  type RouteConfig,
+  route,
+  layout,
+  index,
+} from "@react-router/dev/routes";
+import { rrPulseRouteTree, type RRRouteObject } from "./routes.runtime";
+
+function toDevRoute(node: RRRouteObject): any {
+  const children = (node.children ?? []).map(toDevRoute);
+  if (node.index) return index(node.file!);
+  if (node.path !== undefined) {
+    return children.length ? route(node.path, node.file!, children) : route(node.path, node.file!);
+  }
+  // Layout node (pathless)
+  return layout(node.file!, children);
+}
+
+export const routes = [
+  layout("${pulse_dir}/_layout.tsx", rrPulseRouteTree.map(toDevRoute)),
+] satisfies RouteConfig;
+"""
+)
+
+# Runtime route tree for matching (used by main layout loader)
+ROUTES_RUNTIME_TEMPLATE = Template(
+	"""import type { RouteObject } from "react-router";
+
+export type RRRouteObject = RouteObject & {
+  id: string;
+  uniquePath?: string;
+  children?: RRRouteObject[];
+  file: string;
+}
+
+export const rrPulseRouteTree = ${routes_str} satisfies RRRouteObject[];
+"""
+)

pulse/codegen/utils.py

@@ -0,0 +1,20 @@
+from collections.abc import Iterable
+
+
+class NameRegistry:
+	def __init__(self, names: Iterable[str] | None = None) -> None:
+		self.names: set[str] = set(names or [])
+
+	def register(self, name: str, suffix: str | None = None, allow_rename: bool = True):
+		if name not in self.names:
+			self.names.add(name)
+			return name
+		if not allow_rename:
+			raise ValueError(f"Duplicate identifier {name}")
+		i = 2
+		aliased = f"{name}{i}"
+		while aliased in self.names:
+			i += 1
+			aliased = f"{name}{i}"
+		self.names.add(aliased)
+		return aliased

pulse/component.py

@@ -0,0 +1,237 @@
+"""Component definition and VDOM node types for Pulse.
+
+This module provides the core component abstraction for building Pulse UIs,
+including the `@component` decorator and the `Component` class.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from inspect import Parameter, signature
+from types import CodeType
+from typing import Any, Generic, ParamSpec, TypeVar, overload, override
+
+from pulse.code_analysis import is_stub_function
+from pulse.hooks.init import rewrite_init_blocks
+from pulse.transpiler.nodes import (
+	Children,
+	Node,
+	Primitive,
+	PulseNode,
+	flatten_children,
+)
+from pulse.transpiler.nodes import Element as Element
+from pulse.transpiler.vdom import VDOMNode
+
+P = ParamSpec("P")
+_T = TypeVar("_T")
+
+_COMPONENT_CODES: set[CodeType] = set()
+
+
+def is_component_code(code: CodeType) -> bool:
+	return code in _COMPONENT_CODES
+
+
+class Component(Generic[P]):
+	"""A callable wrapper that turns a function into a Pulse component.
+
+	Component instances are created by the `@component` decorator. When called,
+	they return a `PulseNode` that represents the component in the virtual DOM.
+
+	Attributes:
+		name: Display name of the component (defaults to function name).
+		fn: The underlying render function (lazily initialized for stubs).
+
+	Example:
+
+	```python
+	@ps.component
+	def Card(title: str):
+	    return ps.div(ps.h3(title))
+
+	Card(title="Hello")  # Returns a PulseNode
+	Card(title="Hello", key="card-1")  # With reconciliation key
+	```
+	"""
+
+	_raw_fn: Callable[P, Any]
+	_fn: Callable[P, Any] | None
+	name: str
+	_takes_children: bool | None
+
+	def __init__(self, fn: Callable[P, Any], name: str | None = None) -> None:
+		"""Initialize a Component.
+
+		Args:
+			fn: The function to wrap as a component.
+			name: Custom display name. Defaults to the function's `__name__`.
+		"""
+		self._raw_fn = fn
+		self.name = name or _infer_component_name(fn)
+		# Only lazy-init for stubs (avoid heavy work for JS module bindings)
+		# Real components need immediate rewrite for early error detection
+		if is_stub_function(fn):
+			self._fn = None
+			self._takes_children = None
+		else:
+			self._fn = rewrite_init_blocks(fn)
+			self._takes_children = _takes_children(fn)
+			_COMPONENT_CODES.add(self._fn.__code__)
+
+	@property
+	def fn(self) -> Callable[P, Any]:
+		"""The render function (lazily initialized for stub functions)."""
+		if self._fn is None:
+			self._fn = rewrite_init_blocks(self._raw_fn)
+			self._takes_children = _takes_children(self._raw_fn)
+			_COMPONENT_CODES.add(self._fn.__code__)
+		return self._fn
+
+	def __call__(self, *args: P.args, **kwargs: P.kwargs) -> PulseNode:
+		"""Invoke the component to create a PulseNode.
+
+		Args:
+			*args: Positional arguments passed to the component function.
+			**kwargs: Keyword arguments passed to the component function.
+				The special `key` kwarg is used for reconciliation.
+
+		Returns:
+			A PulseNode representing this component invocation in the VDOM.
+
+		Raises:
+			ValueError: If `key` is provided but is not a string.
+		"""
+		key = kwargs.get("key")
+		if key is not None and not isinstance(key, str):
+			raise ValueError("key must be a string or None")
+
+		# Access self.fn to trigger lazy init (sets _takes_children)
+		_ = self.fn
+		if self._takes_children is True and args:
+			flattened = flatten_children(
+				args,  # pyright: ignore[reportArgumentType]
+				parent_name=f"<{self.name}>",
+				warn_stacklevel=4,
+			)
+			args = tuple(flattened)  # pyright: ignore[reportAssignmentType]
+
+		return PulseNode(fn=self.fn, args=args, kwargs=kwargs, key=key, name=self.name)
+
+	@override
+	def __repr__(self) -> str:
+		return f"Component(name={self.name!r}, fn={_callable_qualname(self._raw_fn)!r})"
+
+	@override
+	def __str__(self) -> str:
+		return self.name
+
+
+@overload
+def component(fn: Callable[P, Any]) -> Component[P]: ...
+
+
+@overload
+def component(
+	fn: None = None, *, name: str | None = None
+) -> Callable[[Callable[P, Any]], Component[P]]: ...
+
+
+# The explicit return type is necessary for the type checker to be happy
+def component(
+	fn: Callable[P, Any] | None = None, *, name: str | None = None
+) -> Component[P] | Callable[[Callable[P, Any]], Component[P]]:
+	"""Decorator that creates a Pulse component from a function.
+
+	Can be used with or without parentheses. The decorated function becomes
+	callable and returns a `PulseNode` when invoked.
+
+	Args:
+		fn: Function to wrap as a component. When used as `@component` without
+			parentheses, this is the decorated function.
+		name: Custom component name for debugging/dev tools. Defaults to the
+			function's `__name__`.
+
+	Returns:
+		A `Component` instance if `fn` is provided, otherwise a decorator.
+
+	Example:
+
+	Basic usage:
+
+	```python
+	@ps.component
+	def Card(title: str):
+	    return ps.div(ps.h3(title))
+	```
+
+	With custom name:
+
+	```python
+	@ps.component(name="MyCard")
+	def card_impl(title: str):
+	    return ps.div(ps.h3(title))
+	```
+
+	With children (use `*children` parameter):
+
+	```python
+	@ps.component
+	def Container(*children):
+	    return ps.div(*children, className="container")
+
+	# Children can be passed via subscript syntax:
+	Container()[
+	    Card(title="First"),
+	    Card(title="Second"),
+	]
+	```
+	"""
+
+	def decorator(fn: Callable[P, Any]) -> Component[P]:
+		return Component(fn, name)
+
+	if fn is not None:
+		return decorator(fn)
+	return decorator
+
+
+def _takes_children(fn: Callable[..., Any]) -> bool:
+	try:
+		sig = signature(fn)
+	except (ValueError, TypeError):
+		return False
+	for p in sig.parameters.values():
+		if p.kind == Parameter.VAR_POSITIONAL and p.name == "children":
+			return True
+	return False
+
+
+# ----------------------------------------------------------------------------
+# Formatting helpers
+# ----------------------------------------------------------------------------
+
+
+def _infer_component_name(fn: Callable[..., Any]) -> str:
+	name = getattr(fn, "__name__", None)
+	if name:
+		return name
+	return "Component"
+
+
+def _callable_qualname(fn: Callable[..., Any]) -> str:
+	mod = getattr(fn, "__module__", "<unknown>")
+	qname = getattr(fn, "__qualname__", getattr(fn, "__name__", "<callable>"))
+	return f"{mod}.{qname}"
+
+
+__all__ = [
+	"Node",
+	"Children",
+	"Component",
+	"Element",
+	"Primitive",
+	"VDOMNode",
+	"component",
+	"is_component_code",
+]