feat: introduce reactive router.path as a State object to enable dynamic UI styling based on the current route

Author: manatlan

.agent/skills/htag-development/SKILL.md

@@ -352,6 +352,7 @@ For multi-page behavior in a Single Page Application (SPA), use the built-in `Ro
 - **Automatic Lifecycle**: `on_mount()` and `on_unmount()` are called automatically when swapping pages.
 - **Route Parameters**: Dynamic segments (e.g., `:id`) are injected directly as keyword arguments into the page's `init()`.
 - **Programmatic Navigation**: Use `router.navigate("/new-path")` to steer the UI from Python.
+- **Reactive Path**: `router.path` is a `State("")` reflecting the current route, enabling reactive tab/link styling.
 
 ```python
 from htag import Tag, Router
@@ -379,7 +380,12 @@ class App(Tag.App):
         self.router.add_route("/", HomePage)
         self.router.add_route("/users/:id", UserPage)
 
-        # 3. Add it to the UI
+        # 3. Navigation with active link highlighting (reactive!)
+        with Tag.nav():
+            Tag.a("Home",  _href="#/",          _class=lambda: "active" if self.router.path == "/" else "")
+            Tag.a("Users", _href="#/users/42",  _class=lambda: "active" if str(self.router.path).startswith("/users") else "")
+        
+        # 4. Add it to the UI
         self <= self.router
 ```
 

docs/routing.md

@@ -78,6 +78,27 @@ def on_login_success(self, e):
 
 This method updates the browser hash, ensuring that the **Back/Forward buttons** continue to work as expected.
 
+## Active Route Styling (`router.path`)
+
+The `router.path` attribute is a reactive `State("")` that always reflects the current route. Use it in lambda attributes to **automatically highlight active navigation links** or tabs:
+
+```python
+class MyApp(Tag.App):
+    def init(self):
+        self.router = Router()
+        self.router.add_route("/", HomePage)
+        self.router.add_route("/settings", SettingsPage)
+
+        # Navigation links with automatic "active" class
+        with Tag.nav():
+            Tag.a("Home",     _href="#/",         _class=lambda: "active" if self.router.path == "/" else "")
+            Tag.a("Settings", _href="#/settings",  _class=lambda: "active" if self.router.path == "/settings" else "")
+
+        self <= self.router
+```
+
+Since `path` is a standard htag `State`, it integrates with the full reactivity system — any component observing it will re-render automatically when the route changes.
+
 ## Custom 404 Pages
 
 If no route matches the current path, a default "404 Not Found" message is displayed. You can customize this by providing your own component:

examples/main_router.py

@@ -4,29 +4,41 @@ class HomePage(Tag.div):
     def init(self) -> None:
         Tag.h1("Home")
         Tag.p("Welcome to this simple SPA demo.")
-        Tag.a("Go to Page 1", _href="#/p1")
-        Tag.br()
-        Tag.a("Go to Hello/World", _href="#/hello/World")
 
 class Page1(Tag.div):
     def init(self) -> None:
         Tag.h1("Page 1")
-        Tag.a("Back Home", _href="#/")
+        Tag.p("This is page 1 content.")
 
 class HelloPage(Tag.div):
     def init(self, name: str) -> None:
         Tag.h1(f"Hello {name}!")
-        Tag.a("Back Home", _href="#/")
 
 class App(Tag.App):
+    statics = [Tag.style("""
+        body { font-family: system-ui; margin: 0; background: #1a1a2e; color: #e0e0e0; }
+        nav { display: flex; gap: 0; background: #16213e; border-bottom: 2px solid #0f3460; }
+        nav a { padding: 12px 24px; text-decoration: none; color: #8899aa;
+                transition: all 0.2s; border-bottom: 2px solid transparent; }
+        nav a:hover { color: #e94560; }
+        nav a.active { color: #e94560; border-bottom-color: #e94560; font-weight: bold; }
+        .content { padding: 32px; }
+    """)]
+
     def init(self) -> None:
         self.router = Router()
-        
         self.router.add_route("/", HomePage)
         self.router.add_route("/p1", Page1)
         self.router.add_route("/hello/:name", HelloPage)
-        
-        self += self.router
+
+        # Navigation with reactive "active" class thanks to router.path (State)
+        with Tag.nav():
+            Tag.a("Home",    _href="#/",            _class=lambda: "active" if self.router.path == "/" else "")
+            Tag.a("Page 1",  _href="#/p1",          _class=lambda: "active" if self.router.path == "/p1" else "")
+            Tag.a("Hello",   _href="#/hello/World",  _class=lambda: "active" if self.router.path == "/hello/World" else "")
+
+        with Tag.div(_class="content"):
+            self <= self.router
 
 if __name__ == "__main__":
     ChromeApp(App).run(reload=True, port=0)

htag/router.py

@@ -22,7 +22,7 @@ def init(self):
 from dataclasses import dataclass, field
 from typing import Any
 
-from .core import GTag
+from .core import GTag, State
 
 logger = logging.getLogger("htag")
 
@@ -73,13 +73,18 @@ class Router(GTag):
 
     Route parameters (e.g. `:id` in `/tasks/:id`) are passed as keyword
     arguments to the page component's init().
+
+    The `path` attribute is a reactive `State("")` holding the current route.
+    Use it in lambdas to style active navigation links::
+
+        Tag.a("Home", _href="#/", _class=lambda: "active" if router.path == "/" else "")
     """
 
     tag: str = "div"
 
     def init(self, **kwargs: Any) -> None:
         self._routes: list[_Route] = []
-        self._current_path: str = ""
+        self.path: State = State("")
         self._not_found_component: type[GTag] | None = None
 
     def add_route(self, path: str, component: type[GTag]) -> None:
@@ -137,8 +142,8 @@ def _on_hash_change(self, event: Any) -> None:
 
     def _navigate_to(self, path: str) -> None:
         """Match a path against registered routes and swap the view."""
-        logger.debug("Router: navigating to '%s' (current='%s')", path, self._current_path)
-        if path == self._current_path and self._current_path != "":
+        logger.debug("Router: navigating to '%s' (current='%s')", path, self.path)
+        if path == self.path and self.path != "":
             return  # Already on this page
 
         for route in self._routes:
@@ -147,13 +152,13 @@ def _navigate_to(self, path: str) -> None:
                 params = match.groupdict()
                 logger.info("Router match: %s → %s(%s)", path, route.component.__name__, params)
                 self._swap(route.component, params)
-                self._current_path = path
+                self.path.value = path
                 return
 
         # No match → 404
         logger.warning("Router: no route matched for '%s'", path)
         self._swap_not_found(path)
-        self._current_path = path
+        self.path.value = path
 
     def _swap(self, component_class: type[GTag], params: dict[str, str]) -> None:
         """Replace the current view with a new component instance."""

tests/test_router.py

@@ -72,5 +72,29 @@ def test_router_initial_route_event():
     router.add_route("/", Page1)
 
     # Simulate htag_event from JS
-    router._on_init_route(type('Event', (object,), {'value': {'hash': '#/'}}))
+    router._on_init_route(type('Event', (object,), {'value': {'hash': '#/'}})())
     assert isinstance(router.childs[0], Page1)
+
+def test_router_path_is_reactive_state():
+    """router.path should be a State, enabling reactive tab styling."""
+    from htag.core import State
+    router = Router()
+    router.add_route("/", Page1)
+    router.add_route("/hello/:name", Page2)
+    
+    # path is a State instance
+    assert isinstance(router.path, State)
+    
+    # Initially empty
+    assert router.path == ""
+    
+    # After navigation, path reflects the route
+    router._navigate_to("/")
+    assert router.path == "/"
+    
+    router._navigate_to("/hello/World")
+    assert router.path == "/hello/World"
+    
+    # Comparison operators work (essential for lambda: "active" if router.path == "/" else "")
+    assert router.path != "/"
+    assert router.path == "/hello/World"

tests/test_router_coverage.py

@@ -13,11 +13,11 @@ class MockEvent:
         def __init__(self, url): self.newURL = url
 
     router._on_hash_change(MockEvent("http://localhost/#/p"))
-    assert router._current_path == "/p"
+    assert router.path == "/p"
 
     # Test line 137: fallback to / (already on /p, so it should clear and hit / which is 404)
     router._on_hash_change(MockEvent("http://localhost/"))
-    assert router._current_path == "/"
+    assert router.path == "/"
     assert "404" in str(router.childs[0])
 
 def test_router_init_route_legacy_event():
@@ -28,7 +28,7 @@ def test_router_init_route_legacy_event():
     class LegacyEvent:
         hash = "#/home"
     router._on_init_route(LegacyEvent())
-    assert router._current_path == "/home"
+    assert router.path == "/home"
 
 def test_router_redundant_navigation():
     router = Router()