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

pulse/codegen/codegen.py

@@ -14,7 +14,7 @@ from pulse.codegen.templates.routes_ts import (
 )
 from pulse.env import env
 from pulse.routing import Layout, Route, RouteTree
-from pulse.transpiler import get_registered_imports
+from pulse.transpiler.assets import get_registered_assets
 
 if TYPE_CHECKING:
 	from pulse.app import ConnectionStatusConfig
@@ -24,13 +24,32 @@ logger = logging.getLogger(__file__)
 
 @dataclass
 class CodegenConfig:
-	"""
-	Configuration for code generation.
+	"""Configuration for code generation output paths.
+
+	Controls where generated React Router files are written. All paths
+	can be relative (resolved against base_dir) or absolute.
+
+	Args:
+		web_dir: Root directory for web output. Defaults to "web".
+		pulse_dir: Subdirectory for generated Pulse files. Defaults to "pulse".
+		base_dir: Base directory for resolving relative paths. If not provided,
+			resolved from PULSE_APP_FILE, PULSE_APP_DIR, or cwd.
 
 	Attributes:
-	    web_dir (str): Root directory for the web output.
-	    pulse_dir (str): Name of the Pulse app directory.
-	    pulse_path (Path): Full path to the generated app directory.
+		web_dir: Root directory for web output.
+		pulse_dir: Subdirectory name for generated files.
+		base_dir: Explicit base directory, if provided.
+
+	Example:
+		```python
+		app = ps.App(
+		    codegen=ps.CodegenConfig(
+		        web_dir="frontend",
+		        pulse_dir="generated",
+		    ),
+		)
+		# Generated files will be at: frontend/app/generated/
+		```
 	"""
 
 	web_dir: Path | str = "web"
@@ -46,11 +65,14 @@ class CodegenConfig:
 	def resolved_base_dir(self) -> Path:
 		"""Resolve the base directory where relative paths should be anchored.
 
-		Precedence:
-		  1) Explicit `base_dir` if provided
-		  2) Env var `PULSE_APP_FILE` (directory of the file)
-		  3) Env var `PULSE_APP_DIR`
-		  4) Current working directory
+		Returns:
+			Resolved base directory path.
+
+		Resolution precedence:
+			1. Explicit `base_dir` if provided
+			2. Directory of PULSE_APP_FILE env var
+			3. PULSE_APP_DIR env var
+			4. Current working directory
 		"""
 		if isinstance(self.base_dir, Path):
 			return self.base_dir
@@ -64,7 +86,11 @@ class CodegenConfig:
 
 	@property
 	def web_root(self) -> Path:
-		"""Absolute path to the web root directory (e.g. `<app_dir>/pulse-web`)."""
+		"""Absolute path to the web root directory.
+
+		Returns:
+			Absolute path to web_dir (e.g., `<base_dir>/web`).
+		"""
 		wd = Path(self.web_dir)
 		if wd.is_absolute():
 			return wd
@@ -72,7 +98,12 @@ class CodegenConfig:
 
 	@property
 	def pulse_path(self) -> Path:
-		"""Full path to the generated app directory."""
+		"""Full path to the generated Pulse app directory.
+
+		Returns:
+			Absolute path where generated files are written
+			(e.g., `<web_root>/app/<pulse_dir>`).
+		"""
 		return self.web_root / "app" / self.pulse_dir
 
 
@@ -123,7 +154,7 @@ class Codegen:
 		self._copied_files = set()
 
 		# Copy all registered local files to the assets directory
-		asset_import_paths = self._copy_local_files()
+		self._copy_local_files()
 
 		# Keep track of all generated files
 		generated_files = set(
@@ -137,11 +168,7 @@ class Codegen:
 				self.generate_routes_ts(),
 				self.generate_routes_runtime_ts(),
 				*(
-					self.generate_route(
-						route,
-						server_address=server_address,
-						asset_import_paths=asset_import_paths,
-					)
+					self.generate_route(route, server_address=server_address)
 					for route in self.routes.flat_tree.values()
 				),
 			]
@@ -157,52 +184,27 @@ class Codegen:
 				except Exception as e:
 					logger.warning(f"Could not remove stale file {path}: {e}")
 
-	def _copy_local_files(self) -> dict[str, str]:
-		"""Copy all registered local files to the assets directory.
+	def _copy_local_files(self) -> None:
+		"""Copy all registered local assets to the assets directory.
 
-		Collects all Import objects with is_local=True and copies their
-		source files to the assets folder, returning an import path mapping.
+		Uses the unified asset registry which tracks local files from both
+		Import objects and DynamicImport expressions.
 		"""
-		imports = get_registered_imports()
-		local_imports = [imp for imp in imports if imp.is_local]
+		assets = get_registered_assets()
 
-		if not local_imports:
-			return {}
+		if not assets:
+			return
 
 		self.assets_folder.mkdir(parents=True, exist_ok=True)
-		asset_import_paths: dict[str, str] = {}
-
-		for imp in local_imports:
-			if imp.source_path is None:
-				continue
 
-			asset_filename = imp.asset_filename()
-			dest_path = self.assets_folder / asset_filename
+		for asset in assets:
+			dest_path = self.assets_folder / asset.asset_filename
 
 			# Copy file if source exists
-			if imp.source_path.exists():
-				shutil.copy2(imp.source_path, dest_path)
+			if asset.source_path.exists():
+				shutil.copy2(asset.source_path, dest_path)
 				self._copied_files.add(dest_path)
-				logger.debug(f"Copied {imp.source_path} -> {dest_path}")
-
-			# Store just the asset filename - the relative path is computed per-route
-			asset_import_paths[imp.src] = asset_filename
-
-		return asset_import_paths
-
-	def _compute_asset_prefix(self, route_file_path: str) -> str:
-		"""Compute the relative path prefix from a route file to the assets folder.
-
-		Args:
-			route_file_path: The route's file path (e.g., "users/_id_xxx.jsx")
-
-		Returns:
-			The relative path prefix (e.g., "../assets/" or "../../assets/")
-		"""
-		# Count directory depth: each "/" in the path adds one level
-		depth = route_file_path.count("/")
-		# Add 1 for the routes/ or layouts/ folder itself
-		return "../" * (depth + 1) + "assets/"
+				logger.debug(f"Copied {asset.source_path} -> {dest_path}")
 
 	def generate_layout_tsx(
 		self,
@@ -281,21 +283,18 @@ class Codegen:
 		self,
 		route: Route | Layout,
 		server_address: str,
-		asset_import_paths: dict[str, str],
 	):
 		route_file_path = route.file_path()
 		if isinstance(route, Layout):
 			output_path = self.output_folder / "layouts" / route_file_path
+			full_route_path = f"layouts/{route_file_path}"
 		else:
 			output_path = self.output_folder / "routes" / route_file_path
-
-		# Compute asset prefix based on route depth
-		asset_prefix = self._compute_asset_prefix(route_file_path)
+			full_route_path = f"routes/{route_file_path}"
 
 		content = generate_route(
 			path=route.unique_path(),
-			asset_filenames=asset_import_paths,
-			asset_prefix=asset_prefix,
+			route_file_path=full_route_path,
 		)
 		return write_file_if_changed(output_path, content)
 

pulse/codegen/templates/route.py

@@ -10,24 +10,29 @@ from pulse.transpiler 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],
-	asset_filenames: dict[str, str] | None = None,
-	asset_prefix: str = "../assets/",
 ) -> 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
-		asset_filenames: Mapping of original source paths to asset filenames
-		asset_prefix: Relative path prefix from route file to assets folder
 	"""
 	default_imports: list[Import] = []
 	namespace_imports: list[Import] = []
@@ -53,8 +58,10 @@ def _generate_import_statement(
 
 	# Remap source path if this is a local import
 	import_src = src
-	if asset_filenames and src in asset_filenames:
-		import_src = asset_prefix + asset_filenames[src]
+	for imp in imports:
+		if imp.asset:
+			import_src = imp.asset.import_path()
+			break
 
 	lines: list[str] = []
 
@@ -98,17 +105,11 @@ def _generate_import_statement(
 	return "\n".join(lines)
 
 
-def _generate_imports_section(
-	imports: Sequence[Import],
-	asset_filenames: dict[str, str] | None = None,
-	asset_prefix: str = "../assets/",
-) -> str:
+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
-		asset_filenames: Mapping of original source paths to asset filenames
-		asset_prefix: Relative path prefix from route file to assets folder
+		imports: List of Import objects to generate (should be eager imports only)
 	"""
 	if not imports:
 		return ""
@@ -163,15 +164,46 @@ def _generate_imports_section(
 
 	lines: list[str] = []
 	for src in ordered:
-		stmt = _generate_import_statement(
-			src, grouped[src], asset_filenames, asset_prefix
-		)
+		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:
@@ -232,64 +264,76 @@ def _generate_registry_section(
 
 def generate_route(
 	path: str,
-	asset_filenames: dict[str, str] | None = None,
-	asset_prefix: str = "../assets/",
+	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")
-		asset_filenames: Mapping of original source paths to asset filenames
-		asset_prefix: Relative path prefix from route file to assets folder
+		route_file_path: Path from pulse root (e.g., "routes/users/index.tsx")
 	"""
-	# Note: Lazy component support is not yet implemented.
-	# Components now register via the unified registry.
+	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)
 
-	# Add core Pulse imports
-	pulse_view_import = Import("PulseView", "pulse-ui-client")
-
-	# Collect function graph (constants + functions in dependency order)
-	constants, funcs = collect_function_graph(registered_functions())
-
-	# Get all registered imports
-	all_imports = list(get_registered_imports())
+		output_parts.append("")
 
-	# Generate output sections
-	output_parts: list[str] = []
+		# Lazy imports (factory functions)
+		lazy_section = _generate_lazy_imports_section(lazy_imports)
+		if lazy_section:
+			output_parts.append(lazy_section)
+			output_parts.append("")
 
-	imports_section = _generate_imports_section(
-		all_imports, asset_filenames, asset_prefix
-	)
-	if imports_section:
-		output_parts.append(imports_section)
+		if constants:
+			output_parts.append(_generate_constants_section(constants))
+			output_parts.append("")
 
-	output_parts.append("")
+		if funcs:
+			output_parts.append(_generate_functions_section(funcs))
+			output_parts.append("")
 
-	if constants:
-		output_parts.append(_generate_constants_section(constants))
+		# Generate the unified registry including all imports, constants and functions
+		output_parts.append(_generate_registry_section(all_imports, constants, funcs))
 		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}";
+		# 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("")
+		output_parts.append("")
 
-	# Headers function
-	output_parts.append("""// Action and loader headers are not returned automatically
+		# Headers function
+		output_parts.append("""// Action and loader headers are not returned automatically
 function hasAnyHeaders(headers) {
   return [...headers].length > 0;
 }
@@ -298,4 +342,4 @@ export function headers({ actionHeaders, loaderHeaders }) {
   return hasAnyHeaders(actionHeaders) ? actionHeaders : loaderHeaders;
 }""")
 
-	return "\n".join(output_parts)
+		return "\n".join(output_parts)

pulse/component.py

@@ -1,9 +1,17 @@
+"""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,
@@ -18,23 +26,89 @@ 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]):
-	fn: Callable[P, Any]
+	"""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
+	_takes_children: bool | None
 
 	def __init__(self, fn: Callable[P, Any], name: str | None = None) -> None:
-		self.fn = rewrite_init_blocks(fn)
+		"""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)
-		self._takes_children = _takes_children(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")
 
-		if self._takes_children and args:
+		# 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}>",
@@ -46,7 +120,7 @@ class Component(Generic[P]):
 
 	@override
 	def __repr__(self) -> str:
-		return f"Component(name={self.name!r}, fn={_callable_qualname(self.fn)!r})"
+		return f"Component(name={self.name!r}, fn={_callable_qualname(self._raw_fn)!r})"
 
 	@override
 	def __str__(self) -> str:
@@ -67,6 +141,53 @@ def component(
 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)
 
@@ -112,4 +233,5 @@ __all__ = [
 	"Primitive",
 	"VDOMNode",
 	"component",
+	"is_component_code",
 ]

pulse/components/for_.py

@@ -1,3 +1,8 @@
+"""For loop component for mapping items to elements.
+
+Provides a declarative way to render lists, similar to JavaScript's Array.map().
+"""
+
 from collections.abc import Callable, Iterable
 from inspect import Parameter, signature
 from typing import TYPE_CHECKING, Any, TypeVar, overload
@@ -27,11 +32,32 @@ def For(items: Iterable[T], fn: Callable[[T, int], Element]) -> list[Element]: .
 
 
 def For(items: Iterable[T], fn: Callable[..., Element]) -> list[Element]:
-	"""Map items to elements, passing `(item)` or `(item, index)`.
+	"""Map items to elements, like JavaScript's Array.map().
+
+	Iterates over `items` and calls `fn` for each one, returning a list of
+	elements. The mapper function can accept either one argument (item) or
+	two arguments (item, index).
+
+	Args:
+		items: Iterable of items to map over.
+		fn: Mapper function that receives `(item)` or `(item, index)` and
+			returns an Element. If `fn` has a `*args` parameter, it receives
+			both item and index.
+
+	Returns:
+		A list of Elements, one for each item.
+
+	Example:
+		Single argument (item only)::
+
+			ps.For(users, lambda user: UserCard(user=user, key=user.id))
+
+		With index::
+
+			ps.For(items, lambda item, i: ps.li(f"{i}: {item}", key=str(i)))
 
-	The callable `fn` may accept either a single positional argument (the item)
-	or two positional arguments (the item and its index), similar to JavaScript's
-	Array.map. If `fn` declares `*args`, it will receive `(item, index)`.
+	Note:
+		In transpiled `@javascript` code, `For` compiles to `.map()`.
 	"""
 	try:
 		sig = signature(fn)