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 effective outlet for a URL.

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

@@ -129,6 +129,12 @@ describe("parsing", () => {
     cleanup()
   })
 
+  test("outletForUrl returns the deepest match effective outlet", _t => {
+    expect(RouteDeclarations.Root.outletForUrl("/settings"))->Expect.toBe(Some("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. 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,41 @@ 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 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 makeFunction = switch route.entrypoint {
+      | true =>
+        `
   let make = (~prepareDisposeTimeout=5 * 60 * 1000): array<RelayRouter.Types.route> => {
-    let {prepareRoute, getPrepared} = makePrepareAssets(~loadedRouteRenderers, ~prepareDisposeTimeout)
-
-    [
-      ${Codegen.getRouteDefinition(route, ~indentation=3)}
-    ]
-  }
+    [${makeRouteName}(~prepareDisposeTimeout)]
+  }`
+      | false => ""
+      }
+      `module ${moduleName} = {
+  let outletForUrl = url => RelayRouter.Internal.outletForUrl([${makeRouteName}()], url)${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 +180,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 +195,28 @@ ${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 makeSignature = switch route.entrypoint {
+      | true => `
   let make: (~prepareDisposeTimeout: int=?) => array<RelayRouter.Types.route>
+`
+      | false => ""
+      }
+      `module ${moduleName}: {
+  let outletForUrl: string => option<string>${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.`,
           )
         | _ => ()
         }

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

@@ -116,6 +116,48 @@ external matchPath: (string, string) => option<pathMatch> = "matchPath"
 external matchPathWithOptions: ({"path": string, "end": bool}, string) => option<pathMatch> =
   "matchPath"
 
+type compiledRoutes
+
+@module("./vendor/react-router.js")
+external compileRoutes: array<route> => compiledRoutes = "compileRoutes"
+
+@module("./vendor/react-router.js") @return(nullable)
+external matchCompiledRoutes: (
+  compiledRoutes,
+  RelayRouter__History.location,
+) => option<array<routeMatch>> = "matchCompiledRoutes"
+
+let locationFromUrl = url => {
+  let urlObj = switch (url->String.startsWith("http://"), url->String.startsWith("https://")) {
+  | (true, _) | (_, true) => url
+  | (false, false) =>
+    switch url->String.startsWith("/") {
+    | true => `http://localhost${url}`
+    | false => `http://localhost/${url}`
+    }
+  }->RelayRouter__Bindings.URL.make
+
+  {
+    RelayRouter__History.pathname: urlObj->RelayRouter__Bindings.URL.getPathname,
+    search: urlObj->RelayRouter__Bindings.URL.getSearch->Option.getOr(""),
+    hash: urlObj->RelayRouter__Bindings.URL.getHash,
+    state: urlObj->RelayRouter__Bindings.URL.getState,
+    key: "-",
+  }
+}
+
+let outletForUrl = (routes: array<route>, url: string): option<string> => {
+  let location = url->locationFromUrl
+
+  switch matchCompiledRoutes(routes->compileRoutes, location) {
+  | Some(matches) =>
+    matches
+    ->Array.get(matches->Array.length - 1)
+    ->Option.flatMap(match => match.route.effectiveOutlet)
+  | None => None
+  }
+}
+
 type prepared
 external toObject: Type.Classify.object => {..} = "%identity"
 external objectToPreparedArrayUnsafe: Type.Classify.object => array<prepared> = "%identity"

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

@@ -35,6 +35,8 @@ external matchPath: (string, string) => option<pathMatch> = "matchPath"
 external matchPathWithOptions: ({"path": string, "end": bool}, string) => option<pathMatch> =
   "matchPath"
 
+let outletForUrl: (array<RelayRouter__Types.route>, string) => option<string>
+
 type prepared
 
 module RouteKey: {