[Router] improve comments and consolidate validation logic

packages/router/README.md

@@ -1,17 +1,20 @@
 # Redwood Router
 
-This is the built-in router for Redwood apps. It takes inspiration from Ruby on Rails, React Router, and Reach Router, but is very opinionated in its own way.
+This is the built-in router for Redwood apps.
+It takes inspiration from Ruby on Rails, React Router, and Reach Router, but is very opinionated in its own way.
 
-Redwood Router (RR) is designed to list all routes in a single file, with limited nesting. We prefer this design, as it makes it very easy to track which routes map to which pages.
+The router is designed to list all routes in a single file, with limited nesting.
+We prefer this design, as it makes it very easy to track which routes map to which pages.
 
 ## Package Leads
 
 - [@mojombo](https://github.com/mojombo)
 - [@tobbe](https://github.com/tobbe)
 - [@jtoar](https://github.com/jtoar)
-## Docs (and Features)
-For the complete documentation, see:
-- [RR Doc](https://deploy-preview-848--redwoodjs.netlify.app/docs/redwood-router)
+
+## Docs and Features
+
+For complete documentation, see https://redwoodjs.com/docs/router.
 
 Features include:
 - Private routes
@@ -22,9 +25,7 @@ Features include:
 - and more...
 
 ## Contributing
-Want to make RR even better? Contributions are welcome!
 
-A great way to get started is looking through these open issues:
-- [Current RR GitHub Issues](https://github.com/redwoodjs/redwood/issues?q=is%3Aopen+is%3Aissue+label%3Atopic%2Frouter)
+Want to make the router even better? Contributions are welcome!
 
 If you have questions, you can reach out to the package leads or ask for help in the "Contributors" channels on either [Redwood Discord](https://discord.gg/redwoodjs) or [Redwood Forums](https://community.redwoodjs.com/).

packages/router/ambient.d.ts

@@ -4,33 +4,43 @@ declare global {
   var __REDWOOD__PRERENDERING: boolean
   /**
    * URL or absolute path to the GraphQL serverless function, without the trailing slash.
-   * Example: `./redwood/functions/graphql` or `https://api.redwoodjs.com/graphql`
+   *
+   * @example
+   *
+   * `./redwood/functions/graphql`
+   * `https://api.redwoodjs.com/graphql`
    */
   var RWJS_API_GRAPHQL_URL: string
   /**
    * URL or absolute path to the DbAuth serverless function, without the trailing slash.
-   * Example: `./redwood/functions/auth` or `https://api.redwoodjs.com/auth`
+   *
+   * @example
+   *
+   * `./redwood/functions/auth`
+   * `https://api.redwoodjs.com/auth`
    **/
   var RWJS_API_DBAUTH_URL: string
 
   /**
    * URL or absolute path to serverless functions, without the trailing slash.
-   * Example: `./redwood/functions/` or `https://api.redwoodjs.com/`
+   *
+   * @example
+   *
+   * `./redwood/functions/`
+   * `https://api.redwoodjs.com/`
    **/
   var RWJS_API_URL: string
 
   namespace NodeJS {
     interface Global {
-      /**
-       * This global is set to true by the prerendering CLI command.
-       */
+      /** This global is set to true by the prerendering CLI command. */
       __REDWOOD__PRERENDERING: boolean
 
-      /** URL or absolute path to the GraphQL serverless function */
+      /** URL or absolute path to the GraphQL serverless function. */
       RWJS_API_GRAPHQL_URL: string
-      /** URL or absolute path to the DbAuth serverless function */
+      /** URL or absolute path to the DbAuth serverless function. */
       RWJS_API_DBAUTH_URL: string
-      /** URL or absolute path to serverless functions */
+      /** URL or absolute path to the serverless functions. */
       RWJS_API_URL: string
     }
   }

packages/router/jest.config.js

@@ -1,5 +1,12 @@
 /** @type {import('@jest/types').Config.InitialOptions} */
 module.exports = {
   setupFilesAfterEnv: ['./jest.setup.js'],
+  /**
+   * As of Jest 27, JSDOM is no longer the default. And in 28 it'll be removed.
+   * (That sounds scary, but all we'll actually have to do is install it separately.)
+   *
+   * @see {@link https://jestjs.io/blog/2021/05/25/jest-27#flipping-defaults}
+   * @see {@link https://jestjs.io/blog/2020/05/05/jest-26}
+   */
   testEnvironment: 'jest-environment-jsdom',
 }

packages/router/jest.setup.js

@@ -1 +1,9 @@
+/**
+ * Tests don't actually fail without mocking `scrollTo`,
+ * but if we don't, we get a wall of text about how `window.scrollTo` hasn't been implemented.
+ *
+ * @see {@link https://jestjs.io/docs/manual-mocks#mocking-methods-which-are-not-implemented-in-jsdom}
+ * @see {@link https://github.com/jsdom/jsdom/issues/1422}
+ * @see {@link https://github.com/jsdom/jsdom/pull/2626}
+ */
 global.scrollTo = jest.fn()

packages/router/package.json

@@ -36,5 +36,9 @@
     "test": "jest src",
     "test:watch": "yarn test --watch"
   },
-  "gitHead": "8be6a35c2dfd5aaeb12d55be4f0c77eefceb7762"
+  "gitHead": "8be6a35c2dfd5aaeb12d55be4f0c77eefceb7762",
+  "peerDependencies": {
+    "react": "17.0.2",
+    "react-dom": "17.0.2"
+  }
 }

packages/router/src/index.ts

@@ -1,7 +1,3 @@
-// This is Redwood's routing mechanism. It takes inspiration from both Ruby on
-// Rails' routing approach and from both React Router and Reach Router (the
-// latter of which has closely inspired some of this code).
-
 export { navigate, back } from './history'
 export { Link, NavLink, useMatch, Redirect } from './links'
 export { useLocation, LocationProvider } from './location'
@@ -19,16 +15,20 @@ export * from './route-focus'
 export { parseSearch } from './util'
 
 /**
- * A more specific interface will be generated by
- * babel-plugin-redwood-routes-auto-loader when a redwood project is built
+ * A more-specific interface will be generated by `babel-plugin-redwood-routes-auto-loader`
+ * when a Redwood Project is built.
  *
  * @example
+ *
  * interface AvailableRoutes {
  *   home: (params?: RouteParams<"/">) => "/"
  *   post: (params?: RouteParams<"/posts/{id:Int}">) => "/posts/{id:Int}"
  * }
+ *
+ * Note: keep this here in `index.ts` so that it can be extended via declaration merging.
+ *
+ * @see {@link https://www.typescriptlang.org/docs/handbook/declaration-merging.html}
  */
-// Keep this in index.ts so it can be extended with declaration merging
 export interface AvailableRoutes {
   [key: string]: (
     args?: Record<string | number, string | number | boolean>