@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80

package/skills/links/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: links
-description: URL generation with ctx.href (server), href (client), useHref (mounted), useMount, and scopedHref
-argument-hint: [href|useHref|useMount|scopedHref]
+description: URL generation with ctx.reverse (server), href (client), useHref (mounted), useMount, and scopedReverse
+argument-hint: [href|useHref|useMount|scopedReverse]
 ---
 
 # Links & URL Generation
 
 @rangojs/router provides different href APIs for server and client contexts.
 
-## Server: ctx.href()
+## Server: ctx.reverse()
 
 Available in route handlers via HandlerContext. Resolves named routes using the full route map.
 
 ```typescript
-import { urls, scopedHref } from "@rangojs/router";
+import { urls, scopedReverse } from "@rangojs/router";
 
 export const shopPatterns = urls(({ path, layout }) => [
   layout(<ShopLayout />, () => [
@@ -24,38 +24,97 @@ export const shopPatterns = urls(({ path, layout }) => [
 ]);
 ```
 
-### Resolution priority
+### Resolution rules
 
-1. **Path-based** (`/...`) - returned as-is
-2. **Absolute name** (contains dot: `blog.post`) - global lookup
-3. **Local name** (`cart`) - resolved relative to current route's namespace
+- **`.name`** — local route, resolved within the current `include()` scope
+- **`name`** — global route, from the named-routes definition
 
 ```typescript
 // Inside a handler within shopPatterns (mounted at /shop)
 path("/product/:slug", (ctx) => {
-  ctx.href("cart");                        // "/shop/cart" (local)
-  ctx.href("product", { slug: "widget" }); // "/shop/product/widget" (local + params)
-  ctx.href("blog.post", { slug: "hi" });   // "/blog/hi" (absolute)
-  ctx.href("/about");                      // "/about" (path-based)
+  ctx.reverse(".cart");                        // "/shop/cart" (local)
+  ctx.reverse(".product", { slug: "widget" }); // "/shop/product/widget" (local + params)
+  ctx.reverse("blog.post", { slug: "hi" });    // "/blog/hi" (global)
 
   return <ProductPage slug={ctx.params.slug} />;
 }, { name: "product" })
 ```
 
-### scopedHref() - type-safe ctx.href
+### Local names (dot-prefixed)
 
-Wraps `ctx.href` with local route type information for autocomplete and validation:
+Prefix a name with `.` to resolve it within the current `include()` scope. The route is looked up using the include's mount namespace.
 
 ```typescript
-import { scopedHref } from "@rangojs/router";
+// urls/magazine.tsx — mounted at include("/magazine", magazinePatterns, { name: "magazine" })
+(ctx) => {
+  ctx.reverse(".article", { slug: "design" }); // "/magazine/design"
+  ctx.reverse(".author.posts", { authorSlug: "alice" }); // "/magazine/author/alice/posts"
+  ctx.reverse(".index"); // "/magazine"
+  ctx.reverse(".blog.index"); // THROWS — no magazine.blog.index
+};
+```
+
+### Auto-fill of mount params
+
+When routes are mounted via a parameterized `include()`, `ctx.reverse()` automatically fills mount params from `ctx.params`. Inner handlers don't need to pass params that are already known from the current URL match. Explicitly passed params override auto-filled values.
+
+```typescript
+// urls/tenant.tsx — mounted at include("/tenant/:tenantId", tenantPatterns, { name: "tenant" })
+export const tenantPatterns = urls(({ path }) => [
+  path("/", (ctx) => {
+    // tenantId is auto-filled from ctx.params — no need to pass it
+    ctx.reverse(".settings");                              // "/tenant/acme/settings" (when visiting /tenant/acme)
+    ctx.reverse(".user", { userId: "u1" });                // "/tenant/acme/users/u1" (tenantId auto-filled, userId explicit)
+    ctx.reverse(".settings", { tenantId: "other" });       // "/tenant/other/settings" (explicit override)
+
+    // Global names also get auto-filled params
+    ctx.reverse("tenant.settings");                        // "/tenant/acme/settings"
+    return <TenantIndex />;
+  }, { name: "index" }),
+  path("/settings", SettingsPage, { name: "settings" }),
+  path("/users/:userId", UserPage, { name: "user" }),
+]);
+```
+
+Auto-fill uses `{ ...ctx.params, ...hrefParams }` — current request params are defaults, explicit params win. Params not needed by the target route are silently ignored.
+
+### Global names (unprefixed)
+
+Unprefixed names resolve against the full named-routes map (the generated `router.named-routes.gen.ts`).
+
+```typescript
+(ctx) => {
+  ctx.reverse("magazine.index"); // "/magazine"
+  ctx.reverse("blog.post", { slug: "hello" }); // "/blog/hello"
+};
+```
+
+### reverse with search params
+
+When a route has a `search` schema, pass a typed search object as the third argument:
+
+```typescript
+path("/search", (ctx) => {
+  // Generates: /search?q=react&page=2
+  const url = ctx.reverse("search", {}, { q: "react", page: 2 });
+  return <Link to={url}>Search React</Link>;
+}, { name: "search", search: { q: "string", page: "number?" } })
+```
+
+### scopedReverse() - type-safe ctx.reverse
+
+Wraps `ctx.reverse` with local route type information for autocomplete and validation:
+
+```typescript
+import { scopedReverse } from "@rangojs/router";
 
 path("/product/:slug", (ctx) => {
-  const href = scopedHref<typeof shopPatterns>(ctx.href);
+  const reverse = scopedReverse<typeof shopPatterns>(ctx.reverse);
 
-  href("cart");                        // Type-safe local name
-  href("product", { slug: "widget" }); // Type-safe with params
-  href("blog.post");                   // Absolute names (dot notation) always allowed
-  href("/about");                      // Path-based always allowed
+  reverse("cart");                        // Type-safe local name
+  reverse("product", { slug: "widget" }); // Type-safe with params
+  reverse("blog.post");                   // Absolute names (dot notation) always allowed
+  reverse("/about");                      // Path-based always allowed
 
   return <ProductPage slug={ctx.params.slug} />;
 }, { name: "product" })
@@ -80,7 +139,9 @@ function GlobalNav() {
 }
 ```
 
-`href()` is an identity function at runtime but provides compile-time validation via `ValidPaths` type. Paths are validated against registered route patterns using `PatternToPath`.
+`href()` provides compile-time validation via `ValidPaths` type. Paths are validated against registered route patterns using `PatternToPath`.
+
+`href()` is a raw path helper — it is **not** basename-aware. It returns the path as-is (or with the include mount prefix via `useHref()`). For basename-aware navigation, use `Link`, `useRouter().push()`, or `reverse()`, which auto-prefix root-relative paths with the router's basename.
 
 ## Client: useHref()
 
@@ -126,24 +187,24 @@ function MountInfo() {
 
 ## When to use what
 
-| Context | API | Resolves | Use for |
-|---------|-----|----------|---------|
-| Server handler | `ctx.href("name")` | Named routes (local + absolute) | Server-side URL generation |
-| Server handler | `scopedHref<T>(ctx.href)` | Same, with type safety | Type-safe server URLs |
-| Client component | `href("/path")` | Absolute paths | Global navigation |
-| Client component | `useHref()` | Mount-prefixed paths | Local navigation inside `include()` |
-| Client component | `useMount()` | Raw mount path | Custom mount-aware logic |
+| Context          | API                             | Resolves                        | Use for                             |
+| ---------------- | ------------------------------- | ------------------------------- | ----------------------------------- |
+| Server handler   | `ctx.reverse("name")`           | Named routes (local + absolute) | Server-side URL generation          |
+| Server handler   | `scopedReverse<T>(ctx.reverse)` | Same, with type safety          | Type-safe server URLs               |
+| Client component | `href("/path")`                 | Absolute paths                  | Global navigation                   |
+| Client component | `useHref()`                     | Mount-prefixed paths            | Local navigation inside `include()` |
+| Client component | `useMount()`                    | Raw mount path                  | Custom mount-aware logic            |
 
 ## Complete example: mounted module
 
 ```typescript
 // urls/shop.tsx (server)
-import { urls, scopedHref } from "@rangojs/router";
+import { urls, scopedReverse } from "@rangojs/router";
 
 export const shopPatterns = urls(({ path, layout }) => [
   layout((ctx) => {
-    const href = scopedHref<typeof shopPatterns>(ctx.href);
-    return <ShopLayout cartUrl={href("cart")} />;
+    const reverse = scopedReverse<typeof shopPatterns>(ctx.reverse);
+    return <ShopLayout cartUrl={reverse("cart")} />;
   }, () => [
     path("/", ShopIndex, { name: "index" }),
     path("/cart", CartPage, { name: "cart" }),