@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.21

package/skills/layout/SKILL.md

@@ -1,216 +1,310 @@
 ---
 name: layout
-description: Define layout routes that wrap child routes in rsc-router
-argument-hint: [layout-name]
+description: Define layout routes that wrap child routes in @rangojs/router
+argument-hint: [component]
 ---
 
-# Layout Routes
+# Layouts with layout()
 
-Layouts wrap child routes and stack vertically from parent to child.
+Layouts wrap child routes and persist during navigation within their scope.
+
+Canonical semantics reference:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
 
 ## Basic Layout
 
 ```typescript
-import { map } from "rsc-router/server";
-import { Outlet } from "rsc-router";
+import { urls } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
 
-// Layout component
-function ShopLayout({ children }: { children: React.ReactNode }) {
+function ShopLayout() {
   return (
     <div className="shop">
-      <ShopHeader />
-      <div className="shop-content">
-        {children}
-      </div>
-      <ShopFooter />
+      <nav>Shop Navigation</nav>
+      <Outlet />  {/* Child routes render here */}
     </div>
   );
 }
 
-// Handler definition
-export default map<typeof routes>(({ route, layout }) => [
+export const urlpatterns = urls(({ path, layout }) => [
   layout(<ShopLayout />, () => [
-    route("index", ShopIndex),
-    route("products", ProductList),
-    route("cart", Cart),
+    path("/shop", ShopIndex, { name: "shop.index" }),
+    path("/shop/cart", CartPage, { name: "shop.cart" }),
+    path("/shop/product/:slug", ProductPage, { name: "shop.product" }),
   ]),
 ]);
 ```
 
-## Nested Layouts
+## Layout Patterns
 
-Layouts can be nested - they stack from parent to child:
+### JSX Element
 
 ```typescript
-export default map<typeof routes>(({ route, layout }) => [
-  // Root layout wraps everything
-  layout(<RootLayout />, () => [
-    route("index", HomePage),
-
-    // Shop layout nested inside root
-    layout(<ShopLayout />, () => [
-      route("shop.index", ShopIndex),
-      route("shop.products", ProductList),
-
-      // Account layout nested inside shop
-      layout(<AccountLayout />, () => [
-        route("shop.account.index", AccountIndex),
-        route("shop.account.orders", OrderList),
-      ]),
-    ]),
+layout(<ShopLayout />, () => [
+  path("/shop", ShopIndex, { name: "shop" }),
+])
+```
+
+### Component Function
 
-    // Blog layout also inside root (sibling to shop)
-    layout(<BlogLayout />, () => [
-      route("blog.index", BlogIndex),
-      route("blog.post", BlogPost),
+```typescript
+layout(ShopLayout, () => [path("/shop", ShopIndex, { name: "shop" })]);
+```
+
+### Handler with Context
+
+```typescript
+layout((ctx) => {
+  const push = ctx.use(Breadcrumbs);
+  push({ label: "Shop", href: "/shop" });
+  return <ShopLayout />;
+}, () => [
+  path("/shop", ShopIndex, { name: "shop" }),
+])
+```
+
+## Nested Layouts
+
+Layouts compose by wrapping order (first layout wraps outer):
+
+```typescript
+urls(({ path, layout }) => [
+  layout(<RootLayout />, () => [           // Outer
+    layout(<ShopLayout />, () => [         // Inner
+      path("/shop", ShopIndex, { name: "shop" }),
     ]),
   ]),
-]);
+])
+
+// Result: RootLayout > ShopLayout > ShopIndex
 ```
 
-Result for `/shop/account/orders`:
+## Layout with Children DSL
+
+Add loaders, parallel routes, or revalidation to layouts:
+
+```typescript
+layout(<ShopLayout />, () => [
+  // Loaders for layout
+  loader(CartLoader),
+  loader(UserLoader),
+
+  // Revalidation rules for layout
+  revalidate(shopRevalidation),
+
+  // Child routes
+  path("/shop", ShopIndex, { name: "shop" }),
+  path("/shop/cart", CartPage, { name: "cart" }),
+])
 ```
-<RootLayout>
-  <ShopLayout>
-    <AccountLayout>
-      <OrderList />
-    </AccountLayout>
-  </ShopLayout>
-</RootLayout>
+
+## The Outlet Component
+
+`<Outlet />` renders child content. Import from `@rangojs/router/client`:
+
+```typescript
+import { Outlet } from "@rangojs/router/client";
+
+function ShopLayout() {
+  return (
+    <div className="shop-layout">
+      <header>Shop Header</header>
+      <main>
+        <Outlet />  {/* Child routes render here */}
+      </main>
+      <footer>Shop Footer</footer>
+    </div>
+  );
+}
 ```
 
-## Layout with Data Loading
+## Named Outlets
 
-Layouts can fetch data and use middleware:
+For parallel routes, use named outlets:
 
 ```typescript
-export default map<typeof routes>(({ route, layout, loader, middleware }) => [
-  layout(
-    async (ctx) => {
-      const user = await ctx.use(UserLoader);
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+
+function DashboardLayout() {
+  return (
+    <div className="dashboard">
+      <aside>
+        <ParallelOutlet name="@sidebar" />
+      </aside>
+      <main>
+        <Outlet />  {/* Main content */}
+      </main>
+      <aside>
+        <ParallelOutlet name="@notifications" />
+      </aside>
+    </div>
+  );
+}
+```
+
+## Orphan Layout (inside route)
+
+A layout as a child of `path()` wraps the route content and can read
+data set by the route handler via `ctx.get()`. The handler always
+executes before its children.
+
+This handler-first guarantee applies to a single full render pass
+(initial render, prerender, or full HTML re-render). During partial
+action revalidation, only the segments that revalidate are recomputed.
+If an orphan layout depends on data established by an outer handler or
+layout, that outer segment must also revalidate, or the orphan must
+guard/reload the data independently.
+
+```typescript
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+
+urls(({ path, layout, parallel }) => [
+  path("/product/:slug", (ctx) => {
+    const product = await fetchProduct(ctx.params.slug);
+    ctx.set("product", product);
+    return <ProductPage product={product} />;
+  }, { name: "product" }, () => [
+    layout((ctx) => {
+      const product = ctx.get("product");
       return (
-        <DashboardLayout user={user}>
+        <div>
+          <Breadcrumb name={product?.name} />
           <Outlet />
-        </DashboardLayout>
+          <ParallelOutlet name="@related" />
+        </div>
       );
-    },
-    () => [
-      loader(UserLoader),
-      middleware(authMiddleware),
-
-      route("dashboard.index", DashboardIndex),
-      route("dashboard.settings", Settings),
-    ]
-  ),
-]);
+    }, () => [
+      parallel({
+        "@related": (ctx) => {
+          const product = ctx.get("product");
+          return <RelatedProducts category={product?.category} />;
+        },
+      }),
+    ]),
+  ]),
+])
 ```
 
-## Orphan Layouts
+Orphan layouts can call `ctx.get()` to read data set by their parent
+handler. They can also call `ctx.set()`, though the primary pattern is
+for route handlers and middleware to write context variables and for
+orphan layouts to read them.
+
+## Layout Revalidation
 
-A layout without children extends the parent layout:
+Layouts don't revalidate by default. Control with `revalidate()`:
 
 ```typescript
-layout(<RootLayout />, () => [
-  // This route uses RootLayout + ShopLayout
-  layout(<ShopLayout />),
-  route("shop.index", ShopIndex),
+layout(<ShopLayout />, () => [
+  // Never revalidate (default behavior)
+  revalidate(() => false),
 
-  // This route only uses RootLayout
-  route("about", About),
-]);
+  path("/shop", ShopIndex, { name: "shop" }),
+])
+
+// Or revalidate based on conditions
+layout(<CartLayout />, () => [
+  revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+
+  path("/cart", CartPage, { name: "cart" }),
+])
 ```
 
-## Layout with Parallel Slots
+If child segments read data that was established by this layout or by a
+route handler above them, revalidate the outer segment too. Partial
+revalidation does not re-run non-revalidated ancestors just to rebuild
+their `ctx.set()` state.
+
+### Revalidation Contracts
+
+For shared upstream data, define named revalidation functions and reuse
+them on both producer and consumer segments:
 
 ```typescript
-layout(
-  (ctx) => (
-    <DashboardLayout>
-      <ParallelOutlet name="@sidebar" />
-      <main>
-        <Outlet />
-      </main>
-      <ParallelOutlet name="@notifications" />
-    </DashboardLayout>
-  ),
-  () => [
-    parallel({
-      "@sidebar": () => <Sidebar />,
-      "@notifications": () => <NotificationPanel />,
-    }),
-    route("dashboard.index", DashboardIndex),
-  ]
-)
+// revalidation-contracts.ts
+export const revalidateCartData = ({ actionId }) =>
+  actionId?.includes("src/actions/cart.ts#addToCart") ?? false;
 ```
 
-## Layout with Handle Accumulation
-
 ```typescript
-import { createHandle } from "rsc-router";
-
-export const Breadcrumbs = createHandle<{ label: string; href: string }>();
-
-export default map<typeof routes>(({ route, layout }) => [
-  layout(
-    (ctx) => {
-      const push = ctx.use(Breadcrumbs);
-      push({ label: "Home", href: "/" });
-      return <RootLayout><Outlet /></RootLayout>;
-    },
-    () => [
-      layout(
-        (ctx) => {
-          const push = ctx.use(Breadcrumbs);
-          push({ label: "Shop", href: "/shop" });
-          return <ShopLayout><Outlet /></ShopLayout>;
-        },
-        () => [
-          route("shop.index", ShopIndex),
-        ]
-      ),
-    ]
-  ),
+layout(<CartLayout />, () => [
+  revalidate(revalidateCartData), // producer
+  path("/cart", CartPage, { name: "cart" }, () => [
+    revalidate(revalidateCartData), // consumer
+  ]),
 ]);
-
-// In client component
-function BreadcrumbNav() {
-  const crumbs = useHandle(Breadcrumbs);
-  // crumbs = [{ label: "Home", href: "/" }, { label: "Shop", href: "/shop" }]
-}
 ```
 
-## Layout Configuration Options
+If a segment depends on multiple upstream domains, compose multiple
+contracts (`revalidateAuthData`, `revalidateCartData`, and so on).
+
+You can also package them as importable handoff helpers:
 
 ```typescript
-layout(<MyLayout />, () => [
-  loader(LayoutLoader),            // Data for layout
-  middleware(authMiddleware),       // Auth check before layout
-  loading(<LayoutSkeleton />),      // Loading state
-  errorBoundary(<LayoutError />),   // Error boundary
-  revalidate(shouldRevalidate),     // Cache control
+// revalidation-contracts.ts
+import { revalidate } from "@rangojs/router";
 
-  // Child routes
-  route("index", IndexHandler),
-])
+export const revalidateAuthData = ({ actionId }) =>
+  actionId?.includes("src/actions/auth.ts#") ?? false;
+export const revalidateAuth = () => [revalidate(revalidateAuthData)];
+```
+
+```typescript
+layout(<ShellLayout />, () => [
+  revalidateAuth(),
+  path("/account", AccountPage, { name: "account" }, () => [
+    revalidateAuth(),
+  ]),
+]);
 ```
 
-## Layout Component Pattern
+## Complete Example
 
 ```typescript
-// layouts/ShopLayout.tsx
-import { Outlet } from "rsc-router";
+import { urls } from "@rangojs/router";
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
 
-export function ShopLayout({ children }: { children?: React.ReactNode }) {
+function ShopLayout() {
   return (
-    <div className="shop-layout">
-      <ShopNav />
-      <main>
-        {children ?? <Outlet />}
-      </main>
-      <ShopFooter />
+    <div className="shop">
+      <ParallelOutlet name="@promoBanner" />
+      <nav>
+        <a href="/shop">Home</a>
+        <a href="/shop/cart">Cart</a>
+      </nav>
+      <div className="content">
+        <aside>
+          <ParallelOutlet name="@sidebar" />
+        </aside>
+        <main>
+          <Outlet />
+        </main>
+      </div>
     </div>
   );
 }
-```
 
-Use `children` for direct children or `<Outlet />` for route content.
+export const shopPatterns = urls(({ path, layout, parallel, loader, revalidate }) => [
+  layout((ctx) => {
+    const push = ctx.use(Breadcrumbs);
+    push({ label: "Shop", href: "/shop" });
+    return <ShopLayout />;
+  }, () => [
+    // Layout loaders
+    loader(CartLoader, () => [
+      revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+    ]),
+
+    // Parallel routes
+    parallel({
+      "@promoBanner": () => <PromoBanner />,
+      "@sidebar": () => <CategorySidebar />,
+    }),
+
+    // Child routes
+    path("/shop", ShopIndex, { name: "index" }),
+    path("/shop/cart", CartPage, { name: "cart" }),
+    path("/shop/product/:slug", ProductPage, { name: "product" }),
+  ]),
+]);
+```