Add root outlet URL resolution

Author: zth

.changeset/root-outlet-for-url.md

@@ -0,0 +1,5 @@
+---
+"rescript-relay-router": minor
+---
+
+Expose root-scoped route declaration helpers for resolving the typed effective outlet for a URL.

examples/client-rendering/src/routes/__generated__/RouteDeclarations.res

@@ -129,6 +129,14 @@ describe("parsing", () => {
     cleanup()
   })
 
+  test("outletForUrl returns the deepest match effective outlet", _t => {
+    expect(RouteDeclarations.Root.outletForUrl("/settings"))->Expect.toBe(
+      Some(RouteDeclarations.Root.Overlay),
+    )
+    expect(RouteDeclarations.Root.outletForUrl("/todos"))->Expect.toBe(None)
+    expect(RouteDeclarations.Root.outletForUrl("/not-found"))->Expect.toBe(None)
+  })
+
   test("parseRoute correctly decode query params", _t => {
     let queryParams =
       Routes.Root.Todos.Route.parseRoute(

examples/client-rendering/src/routes/__generated__/RouteDeclarations.resi

@@ -221,6 +221,17 @@ let renderer = Routes.Shell.Route.makeRenderer(
 
 Slot routes are still regular routes. They use their normal route renderer, `prepare`, `prepareCode`, query params, path params, links, and preloading. The `outlet` property only controls where the matched branch renders.
 
+The generated route declarations also expose a root-scoped `outletForUrl` helper:
+
+```rescript
+let renderTarget = switch RouteDeclarations.Shell.outletForUrl("/preferences/account") {
+| Some(Overlay) => "overlay"
+| Some(_) | None => "primary"
+}
+```
+
+`outletForUrl` uses the same route matcher as the runtime router and returns the deepest matched route's effective outlet as a typed outlet variant. Effective outlets are inherited by descendants, so a child route under an outlet route reports the same outlet even when the child does not repeat the `outlet` field.
+
 This initial implementation supports one active outlet branch per matched URL. A route tree may declare multiple slots, but a single URL match can only split once into the first descendant route that declares `outlet`.
 
 To create a "catch all" route, use the `*`, character as the route path. Typically used for the "not found" route. Example:

examples/client-rendering/test/UrlEncodingDecoding.test.res

@@ -632,14 +632,17 @@ let addIndentation = (str, indentation) => {
   }
 }
 
-let rec getRouteDefinition = (route: printableRoute, ~indentation): string => {
+let rec getRouteDefinition = (route: printableRoute, ~indentation, ~inheritedOutlet=?): string => {
   let routeName = route.name->RouteName.getFullRouteName
+  let effectiveOutlet = route.outlet->Option.orElse(inheritedOutlet)
   let childrenDefinition = switch route.children {
   | [] => ""
   | children =>
     "\n" ++
     children
-    ->Array.map(route => getRouteDefinition(route, ~indentation=indentation + 1))
+    ->Array.map(route =>
+      getRouteDefinition(route, ~indentation=indentation + 1, ~inheritedOutlet=?effectiveOutlet)
+    )
     ->Array.join(",\n") ++ "\n"
   }
 
@@ -656,6 +659,10 @@ let rec getRouteDefinition = (route: printableRoute, ~indentation): string => {
     | Some(outlet) => `Some("${outlet}")`
     | None => "None"
     }},
+    effectiveOutlet: ${switch effectiveOutlet {
+    | Some(outlet) => `Some("${outlet}")`
+    | None => "None"
+    }},
     loadRouteRenderer,
     preloadCode: (
       ~environment: RescriptRelay.Environment.t,

packages/rescript-relay-router/README.md

@@ -137,25 +137,87 @@ let generateRoutes = (~scaffoldAfter, ~deleteRemoved, ~config) => {
   })
 
   // Write the full route declarations file
-  let entrypointRootModules =
+  let rootRouteMakerName = (route: Types.printableRoute) =>
+    `make${route.name->Types.RouteName.getRouteName}Route`
+  let rec collectRouteOutlets = (route: Types.printableRoute, outlets) => {
+    switch route.outlet {
+    | Some(outlet) =>
+      switch outlets->Array.includes(outlet) {
+      | true => ()
+      | false => outlets->Array.push(outlet)
+      }
+    | None => ()
+    }
+
+    route.children->Array.forEach(child => collectRouteOutlets(child, outlets))
+  }
+  let routeOutlets = (route: Types.printableRoute) => {
+    let outlets = []
+    collectRouteOutlets(route, outlets)
+    outlets
+  }
+  let outletTypeDefinition = outlets =>
+    switch outlets {
+    | [] => "type outlet"
+    | outlets => `type outlet = ${outlets->Array.join(" | ")}`
+    }
+  let outletFromStringDefinition = outlets =>
+    switch outlets {
+    | [] => `let outletFromString: string => option<outlet> = _outlet => None`
+    | outlets =>
+      `let outletFromString: string => option<outlet> = outlet =>
+    switch outlet {
+    ${outlets->Array.map(outlet => `| "${outlet}" => Some(${outlet})`)->Array.join("\n    ")}
+    | _ => None
+    }`
+    }
+  let outletTypeSignature = outlets =>
+    switch outlets {
+    | [] => "type outlet"
+    | outlets => `type outlet = ${outlets->Array.join(" | ")}`
+    }
+  let rootRouteMakers =
+    routes
+    ->Array.map(route => {
+      let makeRouteName = route->rootRouteMakerName
+      `let ${makeRouteName} = (~prepareDisposeTimeout=5 * 60 * 1000): RelayRouter.Types.route => {
+  let {prepareRoute, getPrepared} = makePrepareAssets(~loadedRouteRenderers, ~prepareDisposeTimeout)
+
+${Codegen.getRouteDefinition(route, ~indentation=1)}
+}`
+    })
+    ->Array.join("\n\n")
+
+  let rootModules =
     routes
-    ->Array.filter(route => route.entrypoint)
     ->Array.map(route => {
       let moduleName = route.name->Types.RouteName.getRouteName
-      `module ${moduleName} = {
+      let makeRouteName = route->rootRouteMakerName
+      let outlets = route->routeOutlets
+      let makeFunction = switch route.entrypoint {
+      | true =>
+        `
   let make = (~prepareDisposeTimeout=5 * 60 * 1000): array<RelayRouter.Types.route> => {
-    let {prepareRoute, getPrepared} = makePrepareAssets(~loadedRouteRenderers, ~prepareDisposeTimeout)
+    [${makeRouteName}(~prepareDisposeTimeout)]
+  }`
+      | false => ""
+      }
+      `module ${moduleName} = {
+  let routes = [${makeRouteName}()]
+  let compiledRoutes = routes->RelayRouter.Internal.compileRoutes
 
-    [
-      ${Codegen.getRouteDefinition(route, ~indentation=3)}
-    ]
-  }
+  ${outlets->outletTypeDefinition}
+
+  ${outlets->outletFromStringDefinition}
+
+  let outletForUrl = url =>
+    RelayRouter.Internal.outletForUrl(compiledRoutes, url)->Option.flatMap(outletFromString)${makeFunction}
 }`
     })
     ->Array.join("\n\n")
-  let entrypointRootModulesSection = switch entrypointRootModules {
+  let rootModulesSection = switch rootModules {
   | "" => ""
-  | entrypointRootModules => `${entrypointRootModules}\n\n`
+  | rootModules => `${rootModules}\n\n`
   }
 
   let fileContents = `open RelayRouter__Internal__DeclarationsSupport
@@ -164,12 +226,12 @@ external unsafe_toPrepareProps: 'any => prepareProps = "%identity"
 
 let loadedRouteRenderers: Map.t<string, loadedRouteRenderer> = Map.make()
 
-${entrypointRootModulesSection}let make = (~prepareDisposeTimeout=5 * 60 * 1000): array<RelayRouter.Types.route> => {
-  let {prepareRoute, getPrepared} = makePrepareAssets(~loadedRouteRenderers, ~prepareDisposeTimeout)
+${rootRouteMakers}
 
+${rootModulesSection}let make = (~prepareDisposeTimeout=5 * 60 * 1000): array<RelayRouter.Types.route> => {
   [
     ${routes
-    ->Array.map(route => Codegen.getRouteDefinition(route, ~indentation=1))
+    ->Array.map(route => `${route->rootRouteMakerName}(~prepareDisposeTimeout)`)
     ->Array.join(",\n")}
   ]
 }`
@@ -179,23 +241,31 @@ ${entrypointRootModulesSection}let make = (~prepareDisposeTimeout=5 * 60 * 1000)
   )
 
   // Write interface file as the signature of this will never change
-  let entrypointRootModuleSignatures =
+  let rootModuleSignatures =
     routes
-    ->Array.filter(route => route.entrypoint)
     ->Array.map(route => {
       let moduleName = route.name->Types.RouteName.getRouteName
-      `module ${moduleName}: {
+      let outlets = route->routeOutlets
+      let makeSignature = switch route.entrypoint {
+      | true => `
   let make: (~prepareDisposeTimeout: int=?) => array<RelayRouter.Types.route>
+`
+      | false => ""
+      }
+      `module ${moduleName}: {
+  ${outlets->outletTypeSignature}
+
+  let outletForUrl: string => option<outlet>${makeSignature}
 }`
     })
     ->Array.join("\n\n")
-  let entrypointRootModuleSignaturesSection = switch entrypointRootModuleSignatures {
+  let rootModuleSignaturesSection = switch rootModuleSignatures {
   | "" => ""
-  | entrypointRootModuleSignatures => `${entrypointRootModuleSignatures}\n\n`
+  | rootModuleSignatures => `${rootModuleSignatures}\n\n`
   }
 
   Utils.pathInGeneratedFolder(~config, ~fileName="RouteDeclarations.resi")->Fs.writeFileIfChanged(
-    `${entrypointRootModuleSignaturesSection}let make: (~prepareDisposeTimeout: int=?) => array<RelayRouter.Types.route>`,
+    `${rootModuleSignaturesSection}let make: (~prepareDisposeTimeout: int=?) => array<RelayRouter.Types.route>`,
   )
 
   if scaffoldAfter {

packages/rescript-relay-router/cli/RescriptRelayRouterCli__Codegen.res

@@ -901,11 +901,11 @@ module Decode = {
         let slots = slotsProp->validateSlots(~ctx)
         let outlet = outletProp->validateOutlet(~ctx, ~parentContext)
         let entrypoint = entrypointProp->Validators.validateEntrypoint(~ctx, ~parentContext)
-        switch (entrypoint, name) {
-        | (true, Some({name: "RelayRouter", loc})) =>
+        switch (parentContext.routeDepth, name) {
+        | (0, Some({name: "RelayRouter", loc})) =>
           ctx.addDecodeError(
             ~loc,
-            ~message=`"RelayRouter" cannot be used as an entrypoint route name because it would shadow the router runtime module in generated route declarations.`,
+            ~message=`"RelayRouter" cannot be used as a top-level route name because it would shadow the router runtime module in generated route declarations.`,
           )
         | _ => ()
         }