@rangojs/router 0.16.0 → 0.18.0

package/skills/i18n/SKILL.md

@@ -32,6 +32,12 @@ import { menuRoutes } from "./menu";
 export const urlpatterns = urls(({ include }) => [
   include("/:locale?", menuRoutes, { name: "menu" }),
 ]);
+
+// menu.tsx
+export const menuRoutes = urls(({ path }) => [
+  path("/", MenuIndex, { name: "index" }),
+  path("/c/:slug", MenuCategory, { name: "category" }),
+]);
 ```
 
 URLs that match:
@@ -59,7 +65,8 @@ URLs that match:
 Absent optionals are `undefined` (not `""`), so `??` coalesces correctly:
 
 ```typescript
-import { Handler } from "@rangojs/router";
+import type { Handler } from "@rangojs/router";
+import { resolveLocale } from "../lib/locale";
 
 export const MenuIndex: Handler<"menu.index"> = (ctx) => {
   // ctx.params.locale is `string | undefined`
@@ -87,9 +94,9 @@ import { cookies, headers } from "@rangojs/router";
 
 export const SUPPORTED_LOCALES = ["en", "gb", "fr"] as const;
 export type Locale = (typeof SUPPORTED_LOCALES)[number];
-const DEFAULT_LOCALE: Locale = "en";
+export const DEFAULT_LOCALE: Locale = "en";
 
-const isSupported = (v: string): v is Locale =>
+export const isSupported = (v: string): v is Locale =>
   (SUPPORTED_LOCALES as readonly string[]).includes(v);
 
 export function resolveLocale(ctx: {
@@ -104,24 +111,35 @@ export function resolveLocale(ctx: {
   const accept = headers().get("accept-language") ?? "";
   for (const tag of accept.split(",")) {
     const code = tag.split(";")[0].trim().split("-")[0];
-    if (isSupported(code)) return code as Locale;
+    if (isSupported(code)) return code;
   }
   return DEFAULT_LOCALE;
 }
 ```
 
+`cookies()` and `headers()` read the current request, so the helper works in
+handlers, layouts, loaders, and middleware without passing the request in.
+
 If you want to redirect to the canonical URL when the resolved locale
 doesn't match the URL (e.g., user has `gb` cookie but visits `/`), do
-that in a global middleware so it covers actions too:
+that in global middleware (`router.use()`). Global middleware runs before
+route matching, and its `ctx.params` come from its own pattern — not from
+`include("/:locale?")` — so read the locale segment from the pathname:
 
 ```typescript
+// router.tsx
 import { redirect } from "@rangojs/router";
-
-router.use("/*", async (ctx, next) => {
-  const fromUrl = ctx.params.locale;
-  const resolved = resolveLocale(ctx);
-  if (resolved !== DEFAULT_LOCALE && !fromUrl) {
-    return redirect(`/${resolved}${ctx.url.pathname}`);
+import { DEFAULT_LOCALE, isSupported, resolveLocale } from "./lib/locale";
+
+router.use(async (ctx, next) => {
+  if (ctx.request.method !== "GET") return next(); // leave actions alone
+  const first = ctx.url.pathname.split("/")[1] ?? "";
+  if (!isSupported(first)) {
+    const resolved = resolveLocale({ params: {} }); // cookie → Accept-Language → default
+    if (resolved !== DEFAULT_LOCALE) {
+      const rest = ctx.url.pathname === "/" ? "" : ctx.url.pathname;
+      return redirect(`/${resolved}${rest}${ctx.url.search}`);
+    }
   }
   await next();
 });
@@ -138,9 +156,16 @@ ctx.reverse("menu.index", { locale: "" }); // → "/"
 ctx.reverse("menu.index", { locale: undefined }); // → "/"
 ctx.reverse("menu.index", { locale: "en" }); // → "/en"
 ctx.reverse("menu.category", { locale: "en", slug: "breads" }); // → "/en/c/breads"
-ctx.reverse("menu.category", { slug: "breads" }); // → "/c/breads"
+ctx.reverse("menu.category", { slug: "breads" }); // → "/c/breads" on an unprefixed request
 ```
 
+`ctx.reverse()` auto-fills missing params from the current request, so the
+last call returns `/en/c/breads` when the current URL is `/en/...`. That is
+what you want for in-locale links; to leave the locale, pass it explicitly
+(`{ locale: "fr" }`, or `undefined`/`""` for the bare default). Middleware and
+response routes are the exception: their `ctx.reverse` fills nothing from the
+request, so pass `locale` there explicitly.
+
 If the active locale is the app default and your URL strategy hides it
 (`"en"` → `/`, others → `/<locale>`), normalize before calling reverse:
 
@@ -177,28 +202,27 @@ export async function loadMessages(locale: Locale) {
 
 ### Server layout: hand off to the client provider
 
+A layout handler receives the handler context (not props) and renders its
+children with `<Outlet />`. It sees the matched route's params, including
+`locale` from the include below it:
+
 ```tsx
-// layouts/intl-layout.tsx (server component)
-import type { ReactNode } from "react";
+// layouts/intl-layout.tsx (server)
+import type { Handler } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
 import { resolveLocale } from "../lib/locale";
 import { loadMessages } from "../lib/messages";
 import { IntlClientProvider } from "../components/intl-client-provider";
 
-export async function IntlLayout({
-  ctx,
-  children,
-}: {
-  ctx: any;
-  children: ReactNode;
-}) {
+export const IntlLayout: Handler = async (ctx) => {
   const locale = resolveLocale(ctx);
   const messages = await loadMessages(locale);
   return (
     <IntlClientProvider locale={locale} messages={messages}>
-      {children}
+      <Outlet />
     </IntlClientProvider>
   );
-}
+};
 ```
 
 ### Client provider
@@ -252,20 +276,22 @@ export const urlpatterns = urls(({ layout, include }) => [
 ```
 
 `<FormattedMessage>`, `useIntl()`, etc. work in any client component
-under the layout. Server components can use `formatjs`'s `createIntl()`
-directly with the same `messages` map for static text.
+under the layout. Server components and handlers can't use React context
+providers from the client; call `createIntl({ locale, messages })` (from
+`@formatjs/intl` or `react-intl`) directly with the same `messages` map for
+server-rendered text.
 
 ## Common Pitfalls
 
-| Pitfall                                                       | Fix                                                                                    |
-| ------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `ctx.params.locale === ""` returns `false`                    | Absent optionals are `undefined`, not `""`. Use `=== undefined` or `??`.               |
-| `ctx.params.locale ?? "en"` returns `""`                      | Pre-fix behavior. After the include-prefix fix this works correctly.                   |
-| Bare `/` 404s when mounted via `include("/:locale?", routes)` | Requires the all-optional pattern fix in `compilePattern` (shipped).                   |
-| Unknown locale (e.g. `/de`) matches as `locale: "de"`         | Add a constraint: `:locale(en\|gb\|fr)?`. Unknown values now 404.                      |
-| Reverse produces `//c/breads` for absent locale               | `reverse()` collapses `undefined`/`""` segments — should not happen. File a bug.       |
-| Locale switcher loses search params                           | Read `ctx.url.search` and pass to `reverse(..., undefined, parsedSearch)`.             |
-| Action middleware can't read `ctx.params.locale`              | Route middleware doesn't wrap action execution. Use global `router.use()` for actions. |
+| Pitfall                                                       | Fix                                                                                                                |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `ctx.params.locale === ""` returns `false`                    | Absent optionals are `undefined`, not `""`. Use `=== undefined` or `??`.                                           |
+| Unknown locale (e.g. `/de`) matches as `locale: "de"`         | Add a constraint: `:locale(en\|gb\|fr)?`. Unknown values now 404.                                                  |
+| Link meant for the default locale keeps `/en`                 | `ctx.reverse()` auto-fills the current `locale`. Pass `{ locale: undefined }` (or `""`) to drop it.                |
+| Reverse produces `//c/breads` for absent locale               | `reverse()` collapses `undefined`/`""` segments — should not happen. File a bug.                                   |
+| Locale switcher loses search params                           | Append `ctx.url.search` to the reversed URL, or pass `Object.fromEntries(ctx.searchParams)` as the third argument. |
+| Global middleware's `ctx.params.locale` is always `undefined` | Global middleware params come from its own pattern. Parse the first path segment (see "Locale Resolution").        |
+| Route middleware doesn't see actions                          | Route middleware doesn't wrap action execution. Use global `router.use()` for action-time locale logic.            |
 
 ## Cross-references
 

package/skills/intercept/SKILL.md

@@ -8,6 +8,18 @@ argument-hint: [@slot-name] [route-to-intercept]
 
 Intercept routes render a different component during soft navigation (client-side) while preserving the background route. Hard navigation (direct URL) shows the full page.
 
+`intercept(slot, routeName, handler, config?, use?)`:
+
+- `slot` — the `@name` slot the intercept renders into; the layout places it
+  with `<ParallelOutlet name="@modal" />`.
+- `routeName` — the target route. A dot prefix (`".product"`) resolves inside
+  the current `include()` scope; a bare name (`"product"`) is the global route
+  name. Declare the intercept in a layout that wraps the target route — the
+  router finds intercepts by walking up the target route's own layout chain.
+- `handler` — the component or handler rendered in the slot.
+- `config` — optional `{ when }` (see "Conditional Intercept"); pass the `use`
+  callback as the 4th argument when there is no config.
+
 ## Not this skill if…
 
 - You want a slot that ALWAYS renders alongside the page (sidebar, multi-column
@@ -60,7 +72,8 @@ export const urlpatterns = urls(({ path, layout, intercept, loader, loading }) =
 
 ## Intercept with Layout
 
-Wrap intercept content in a modal layout:
+Wrap intercept content in a modal layout. The layout renders the intercept
+content through `<Outlet />` (not a `children` prop):
 
 ```typescript
 intercept(
@@ -68,21 +81,29 @@ intercept(
   "product",
   <ProductModalContent />,
   () => [
-    layout(<ModalWrapper />),  // Wraps the modal content
+    layout(<ModalWrapper />),  // Wraps the modal content via <Outlet />
     loader(ProductLoader),
     loading(<ProductModalSkeleton />),
   ]
 )
 ```
 
+Only the first `layout()` in an intercept's `use()` is applied. It is modal
+chrome only: a `layout(Chrome, () => [...])` with its own `use()` items throws.
+Attach loaders and the rest to the intercept itself.
+
 ## Intercept Middleware
 
 Intercepts support their own middleware chain via the use callback. The full chain for an intercept request is:
 
 ```
-global mw (router.use) -> route mw (urls middleware()) -> intercept mw -> intercept handler -> intercept loaders
+global mw (router.use) -> route mw (urls middleware()) -> intercept mw -> intercept loaders + handler
 ```
 
+The intercept's loaders are started before its handler is called, so they run
+in parallel with it. If intercept middleware returns a `Response` (e.g. a
+redirect), the intercept stops there.
+
 ```typescript
 intercept(
   "@modal",
@@ -108,22 +129,55 @@ If an intercept depends on data established by an outer layout/handler,
 revalidate that outer segment too or reload/guard the data inside the
 intercept.
 
+### Revalidating an Intercept
+
+An intercept has no segment-level `revalidate()`. Its handler and layout
+re-render every time the intercept resolves live — each intercepted
+navigation, and each action submitted while the modal is open. When the
+segment cache or a prerendered intercept variant serves the modal, the stored
+handler output is reused and only the loaders run. Each loader decides for
+itself through its own `revalidate()`, with the normal loader defaults.
+
+A `revalidate()` placed directly in the intercept's `use()` (or returned from
+its handler's `.use`) throws at definition time. Attach it to the loader:
+
+```typescript
+// Throws: revalidate() is not valid inside intercept("@modal", "product") use()
+intercept("@modal", "product", <ProductModal />, () => [
+  revalidate(() => false),
+  loader(ProductLoader),
+]);
+
+// Correct: the loader owns the decision
+intercept("@modal", "product", <ProductModal />, () => [
+  loader(ProductLoader, () => [revalidate(() => false)]),
+]);
+```
+
 ### Revalidation Contracts for Intercept Dependencies
 
-Use named revalidation contracts on both the outer producer and the intercept
-consumer when they share `ctx.set()` data:
+When an outer layout produces `ctx.set()` data that the intercept reads, the
+producer is the side that needs a contract: outer layouts are skipped during
+partial action revalidation unless they opt in. The intercept side needs none
+by default — its handler re-renders on every action while the modal is open,
+and its loaders re-run after every action. If you narrow an intercept loader
+with its own `revalidate()`, compose the producer's contract into it so the
+two stay in step:
 
 ```typescript
+import type { Revalidate } from "@rangojs/router";
 import * as ProductActions from "./actions/product";
 
-export const revalidateProductShell = (ctx) =>
+export const revalidateProductShell: Revalidate = (ctx) =>
   ctx.isAction(ProductActions) || undefined;
 
 layout(ProductLayout, () => [
   revalidate(revalidateProductShell), // producer reruns
   intercept("@modal", "product", <ProductModal />, () => [
-    revalidate(revalidateProductShell), // consumer reruns
-    loader(ProductLoader),
+    loader(ProductLoader, () => [
+      revalidate(revalidateProductShell), // reruns with the producer
+      revalidate(() => false), // otherwise keep the loaded data
+    ]),
   ]),
 ]);
 ```
@@ -143,17 +197,16 @@ export const revalidateProduct = () => [
 layout(ProductLayout, () => [
   revalidateProduct(),
   intercept("@modal", "product", <ProductModal />, () => [
-    revalidateProduct(),
-    loader(ProductLoader),
+    loader(ProductLoader, () => [revalidateProduct(), revalidate(() => false)]),
   ]),
 ]);
 ```
 
 ## Conditional Intercept with the `when` config
 
-Only intercept based on navigation context. `when` is the 4th argument
-(an `InterceptConfig` object); the other use-items go in the 5th-argument
-callback.
+Only intercept based on navigation context. `when` goes in the config object
+(4th argument); the use-items then move to the 5th-argument callback. The
+config type is not exported — pass an object literal.
 
 ```typescript
 intercept(
@@ -168,9 +221,19 @@ intercept(
 )
 ```
 
-`when` is a match-time selector receiving `{ from, to, params, segments, ... }`.
+`when` is a synchronous match-time selector. It receives `from` / `to` (URLs),
+`fromRouteName` / `toRouteName` (named routes only), `params` (the target's),
+`segments` (the client's current segment path and ids), `request`, and `env`.
 Pass an array of predicates for AND logic (all must return true). Omit `when`
-entirely and the intercept always activates.
+entirely and the intercept always activates. `when` is not re-evaluated during
+action revalidation, so an open modal stays open after an action.
+
+```typescript
+// Intercept only when opened from the shop index
+intercept("@modal", "product", <ProductModal />, {
+  when: ({ fromRouteName }) => fromRouteName === "index",
+})
+```
 
 ```typescript
 intercept(
@@ -204,22 +267,84 @@ intercept(
 )
 ```
 
+## What an Intercept's `use()` Accepts
+
+An intercept's `use()` (and its handler's `.use`) accepts:
+
+- `loader()`, with its own `revalidate()` and `cache()` inside it
+- `middleware()`
+- `loading()`
+- `layout(Chrome)`: the modal chrome, without `use()` items of its own
+- `route`, the item type a `path()` call produces
+- `transition()`
+
+Everything else throws at definition time with a pointer to where it goes:
+`revalidate()` onto the loader, `errorBoundary()` / `notFoundBoundary()` onto
+the enclosing layout (see below), and `cache()` onto the target route.
+
+## Caching an Intercept
+
+To cache a modal, put `cache()` on the target route (or a layout above it).
+An intercept navigation is cached under that scope with its own `intercept:`
+key, so it never collides with the full-page render of the same URL. For
+finer control, use `"use cache"` in the intercept handler, or cache the
+intercept's loader: `loader(ProductLoader, () => [cache()])`.
+
+## Errors in an Intercept
+
+An intercept has no boundary of its own. When the intercept's handler or one
+of its loaders throws, or calls `notFound()`, the modal slot renders the
+`errorBoundary()` / `notFoundBoundary()` of the layout or path that declares the
+intercept, or the nearest ancestor that has one. That holds when the declaring
+layout has no routes of its own, too: the lookup continues at the layout that
+holds it and that layout's ancestors. The intercepted route's own
+boundaries are not consulted: the modal renders in the declaring layout's slot,
+not in the route. On a handler error the modal layout and the background page
+stay mounted, and the status is 500 / 404. A thrown `Response` (`redirect()`)
+still short-circuits the navigation.
+
+With `loading()`, an async handler streams after the response has started, so
+its rejection is not caught on the server. Wrap the modal layout's `<Outlet />`
+in a client error boundary.
+
+An `errorBoundary()` or `notFoundBoundary()` placed directly in the intercept's
+`use()` (or returned from its handler's `.use`) throws at definition time. Put
+it on the enclosing layout:
+
+```typescript
+// Throws: errorBoundary() is not valid inside intercept("@modal", "product") use()
+intercept("@modal", "product", <ProductModal />, () => [
+  loader(ProductLoader),
+  errorBoundary(<ModalError />),
+]);
+
+// Correct: the declaring layout's boundaries handle the intercept's handler and loaders
+layout(<ShopLayout />, () => [
+  errorBoundary(<ShopError />),
+  notFoundBoundary(<ProductNotFound />),
+  intercept("@modal", "product", <ProductModal />, () => [
+    loader(ProductLoader),
+  ]),
+]);
+```
+
 ## Closing the Modal
 
 Use navigation to close:
 
 ```typescript
 "use client";
-import { useRouter } from "@rangojs/router/client";
+import { Outlet, useRouter } from "@rangojs/router/client";
 
-function ModalWrapper({ children }) {
+// Used as the intercept's layout: layout(<ModalWrapper />)
+export function ModalWrapper() {
   const router = useRouter();
 
   return (
     <div className="modal-overlay" onClick={() => router.back()}>
       <div className="modal" onClick={(e) => e.stopPropagation()}>
         <button onClick={() => router.back()}>Close</button>
-        {children}
+        <Outlet />
       </div>
     </div>
   );
@@ -305,10 +430,10 @@ segments.
 ## Complete Example
 
 ```typescript
-// components/ProductModal.tsx
+// components/shop-layout.tsx
 import { Outlet, ParallelOutlet } from "@rangojs/router/client";
 
-function ShopLayout() {
+export function ShopLayout() {
   return (
     <div className="shop">
       <ParallelOutlet name="@promoBanner" />
@@ -320,16 +445,23 @@ function ShopLayout() {
   );
 }
 
-function ModalWrapper({ children }) {
+// components/modal-wrapper.tsx (see "Closing the Modal" for a closable version)
+import { Outlet } from "@rangojs/router/client";
+
+export function ModalWrapper() {
   return (
     <div className="modal-overlay">
-      <div className="modal">{children}</div>
+      <div className="modal">
+        <Outlet />
+      </div>
     </div>
   );
 }
 
-// urls/shop.tsx
+// urls/shop.tsx — mounted with include("/shop", shopPatterns, { name: "shop" })
 import { urls } from "@rangojs/router";
+import { ShopLayout } from "../components/shop-layout";
+import { ModalWrapper } from "../components/modal-wrapper";
 
 export const shopPatterns = urls(({
   path,
@@ -338,6 +470,7 @@ export const shopPatterns = urls(({
   intercept,
   loader,
   loading,
+  cache,
 }) => [
   layout(<ShopLayout />, () => [
     parallel({
@@ -347,7 +480,7 @@ export const shopPatterns = urls(({
     // Intercept product detail into modal
     intercept(
       "@modal",
-      "product",  // Route name (without prefix)
+      ".product", // dot-local: resolves to "shop.product" in this include
       <ProductModalContent />,
       { when: ({ from }) => !from.pathname.startsWith("/shop/product/") },
       () => [
@@ -370,9 +503,11 @@ export const shopPatterns = urls(({
 
 ## Handler-attached `.use`
 
-Intercept handlers can carry their own middleware, loaders, loading state, error/notFound boundaries, and even nested `layout`/`route` defaults via `.use` — useful for self-contained modal components that travel with their own data and chrome. (Conditional activation is set via the `when` config on the mount-site `intercept()` call, not inside `.use`.)
+Intercept handlers can carry their own middleware, loaders, loading state, and even nested `layout`/`route` defaults via `.use` — useful for self-contained modal components that travel with their own data and chrome. (Conditional activation is set via the `when` config on the mount-site `intercept()` call, not inside `.use`; boundaries go on the enclosing layout, see [Errors in an Intercept](#errors-in-an-intercept).)
 
 ```typescript
+import { layout, loader, loading, type Handler } from "@rangojs/router";
+
 const QuickViewModal: Handler = async (ctx) => {
   const product = await ctx.use(ProductLoader);
   return <QuickView product={product} />;
@@ -380,7 +515,7 @@ const QuickViewModal: Handler = async (ctx) => {
 QuickViewModal.use = () => [
   loader(ProductLoader),
   loading(<QuickViewSkeleton />),
-  layout(<ModalChrome />),
+  layout(<ModalChrome />), // ModalChrome renders <Outlet />
 ];
 
 intercept("@modal", "product", QuickViewModal);