Skip to content

RFC 16: Route tables: defineRoute inside a factory, and layout routes #17

Open

Description

@yumemi-thomas

One of a series of small proposals, in order; the tracking issue lists them. Depends on: RFC 15 (#16).

Summary

Two additions for @solidjs/router 2.0's route tables. First, a JS call inside a factory's arguments that is declared forwards, such as defineRoute({ path, component }), passes the components in it on to the factory (MO-11g). Second, a factory declared nests(children in component) has each nested route checked inside its layout's children, so the layout's boundaries and provisions reach it (MO-11i).

Motivation

On upstream (PR solidjs#69), a component is a value only inside the record and array literals of a factory's arguments, a factory being a JS fn declared to return a Component. Every such component is checked as if rendered directly under <Router /> (DV-24). Two things fail with real route tables:

  • @solidjs/router 2.0 recommends defineRoute({ path: "/people/:id", component: Person }), which does nothing at run time but types the component's params from the path. On upstream a component inside that call is not "in the factory's literals", so it is COMPONENT_AS_VALUE.
  • A layout route renders its child routes in its own props.children. Under DV-24 the checker does not know this. A layout that wraps its pages in an errored boundary or a provide gets no credit for them, so a page that fails or reads that context is refused (UNHANDLED_FAILURE, CONTEXT_NOT_FOUND) even though it runs fine.

Proposal

MO-11g (JS calls inside a factory's arguments). forwards on a declared JS fn says it returns what it is given, for a factory or carrier to render. A call to such a fn among a factory's argument literals passes its arguments on to the factory: the components found through that call's own record and array literals are component values of the factory too (MO-11c). A call to a fn without the word passes nothing on; a component in it takes the cautious placement (RFC 19, MO-11s): checked under a root of its own, nothing above the call credited. Bound on its own (route = defineRoute({ … })), even a forwarding call is not part of any route table the checker can see, so the same holds.

MO-11i (Nested values). nests(kids in inside) on a fn that returns a Component says how it renders a record among its arguments: the component in the record's inside field renders the entries in its kids field among its own children. For @solidjs/router:

// router.d.rx
export pure fn createRouter(config: { routes: RouteDefinition[] }): Component nests(children in component)
export pure fn defineRoute(route: RouteDefinition): RouteDefinition forwards

The checker applies the record's component with the nested values as its children, as <Layout><Page /></Layout> would be. A layout's errored, loading and provide above props.children reach its routes, and its content model (SV-7d) applies to them. Sibling records stay siblings. Without the word, DV-24 still applies. On a fn that returns no Component, the word is a parse error.

component Layout(props) {
  provide theme = "dark"
  errored fallback(e) { <p>failed</p> } {
    <main>{props.children}</main>
  }
}
Router = createRouter({ routes: [
  { path: "/", component: Layout, children: [{ path: "/", component: Swatch }, defineRoute({ path: "/page", component: Page })] }
] })

Swatch finds theme, and Page's failure is caught by Layout's boundary. A boundary in the layout counts only if it is above props.children. A nested <div> inside a layout's <p>{props.children}</p> is CONTENT_MODEL.

The word describes the shape of the arguments, not a router. Any library that nests a tree of components it is given says it the same way. RFC 18 adds a second tree form, and MO-11r groups them.

Drawbacks and alternatives

  • The checker trusts the declaration about where nested routes render. rx-verify can check that by running the library (RFC 18).
  • The first prototype passed components through any JS call inside a factory's literals. A review pointed out that an arbitrary wrapper (logged(Page), a lazy loader) may render the component elsewhere or not at all, so crediting the factory's boundaries to it could accept a failure nothing catches. Forwarding is now declared.
  • Alternative: a routing form in the language (design note (b) under MO-11). It was rejected because the form would carry one library's meaning.
  • Alternative: keep DV-24 and tell users to provide contexts above <Router />. That still refuses valid layouts.

Prototype

Branch claude/magical-bell-pfhb1w of yumemi-thomas/reactivescript:

  • 0b1dd95, the MO-11g part: the checker follows JS calls inside a factory's literals.
  • afa696e: only calls declared forwards.
  • c4a5a6f: nests(… in …) in both parsers and checkers, and the router example declares it.

Spec: MO-11g and MO-11i. Scenarios: S-module-8 (defineRoute inside the table; UNHANDLED_FAILURE for a failing page inside an undeclared logged(…) call, which gets no credit for the router's boundaries) and S-module-9 (accepted layout; CONTEXT_NOT_FOUND for a sibling route; UNHANDLED_FAILURE for a boundary beside props.children; CONTENT_MODEL; PARSE for nests on a non-factory). examples/router runs on @solidjs/router 2.0 in the Vite suite. Both implementations (ref/ and the Rust crate) agree.

Revised after the second review (2026-11-21, cdc00d4)

RFC 16, after the second review. MO-11r now states one placement model for RFCs 16–18: where a value is checked (the row), how a tree rearranges values inside that place (nests), how values may travel, and what happens to one nothing consumes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions