add docs for solid-router

Author: atilafassina

src/routes/data.json

@@ -6,6 +6,7 @@
 		"concepts",
 		"advanced-concepts",
 		"guides",
-		"configuration"
+		"configuration",
+		"solid-router"
 	]
 }

src/routes/quick-start.mdx

@@ -11,8 +11,7 @@ Additionally, we offer a [JavaScript](https://stackblitz.com/github/solidjs/temp
 ## Creating a Solid application
 
 <Callout title="Prerequisites:">
-	* Familiarity with the command line
-	* Install [Node.js](https://nodejs.org/en)
+	* Familiarity with the command line * Install [Node.js](https://nodejs.org/en)
 </Callout>
 
 Solid offers convenient project templates that can help kickstart your development.
@@ -41,11 +40,7 @@ npm install
 ```
 </div>
 
-<div id="yarn">
-```bash frame="none" 
-yarn install 
-```
-</div>
+<div id="yarn">```bash frame="none" yarn install ```</div>
 
 <div id="pnpm">
 ```bash frame="none"
@@ -86,11 +81,7 @@ npm install
 ```
 </div>
 
-<div id="yarn">
-```bash frame="none"
-bash yarn install
-```
-</div>
+<div id="yarn">```bash frame="none" bash yarn install ```</div>
 
 <div id="pnpm">
 ```bash frame="none"

src/routes/reference/data.json

@@ -9,6 +9,7 @@
 		"reactive-utilities",
 		"rendering",
 		"secondary-primitives",
-		"stores"
+		"stores",
+		"solid-router"
 	]
 }

src/routes/reference/solid-router/cache.mdx

@@ -0,0 +1,63 @@
+---
+title: cache
+---
+
+To prevent duplicate fetching and to trigger handle refetching we provide a cache api. That takes a function and returns the same function.
+
+```jsx
+const getUser = cache((id) => {
+  return (await fetch(`/api/users${id}`)).json()
+}, "users") // used as cache key + serialized arguments
+```
+
+It is expected that the arguments to the cache function are serializable.
+
+This cache accomplishes the following:
+
+1. It does just deduping on the server for the lifetime of the request.
+2. It does preload cache in the browser which lasts 10 seconds. When a route is preloaded on hover or when load is called when entering a route it will make sure to dedupe calls.
+3. We have a reactive refetch mechanism based on key. So we can tell routes that aren't new to retrigger on action revalidation.
+4. It will serve as a back/forward cache for browser navigation up to 5 mins. Any user based navigation or link click bypasses it. Revalidation or new fetch updates the cache.
+
+Using it with load function might look like:
+
+```js
+import { lazy } from "solid-js";
+import { Route } from "@solidjs/router";
+import { getUser } from ... // the cache function
+
+const User = lazy(() => import("./pages/users/[id].js"));
+
+// load function
+function loadUser({params, location}) {
+  void getUser(params.id)
+}
+
+// Pass it in the route definition
+<Route path="/users/:id" component={User} load={loadUser} />;
+```
+
+Inside your page component you:
+
+```jsx
+// pages/users/[id].js
+import { getUser } from ... // the cache function
+
+export default function User(props) {
+  const user = createAsync(() => getUser(props.params.id));
+  return <h1>{user().name}</h1>;
+}
+```
+
+Cached function has a few useful methods for getting the key that are useful for invalidation.
+
+```ts
+let id = 5;
+
+getUser.key; // returns "users"
+getUser.keyFor(id); // returns "users[5]"
+```
+
+You can revalidate the cache using the `revalidate` method or you can set `revalidate` keys on your response from your actions. If you pass the whole key it will invalidate all the entries for the cache (ie "users" in the example above). You can also invalidate a single entry by using `keyFor`.
+
+`cache` can be defined anywhere and then used inside your components with:

src/routes/reference/solid-router/components/a.mdx

@@ -0,0 +1,17 @@
+---
+title: A
+---
+
+Like the `<a>` tag but supports relative paths and active class styling (requires client side JavaScript).
+
+The `<A>` tag has an `active` class if its href matches the current location, and `inactive` otherwise. **Note:** By default matching includes locations that are descendents (eg. href `/users` matches locations `/users` and `/users/123`), use the boolean `end` prop to prevent matching these. This is particularly useful for links to the root route `/` which would match everything.
+
+| prop          | type    | description                                                                                                                                                                              |
+| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| href          | string  | The path of the route to navigate to. This will be resolved relative to the route that the link is in, but you can preface it with `/` to refer back to the root.                        |
+| noScroll      | boolean | If true, turn off the default behavior of scrolling to the top of the new page                                                                                                           |
+| replace       | boolean | If true, don't add a new entry to the browser history. (By default, the new page will be added to the browser history, so pressing the back button will take you to the previous route.) |
+| state         | unknown | [Push this value](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState) to the history stack when navigating                                                               |
+| inactiveClass | string  | The class to show when the link is inactive (when the current location doesn't match the link)                                                                                           |
+| activeClass   | string  | The class to show when the link is active                                                                                                                                                |
+| end           | boolean | If `true`, only considers the link to be active when the curent location matches the `href` exactly; if `false`, check if the current location _starts with_ `href`                      |

src/routes/reference/solid-router/components/data.json

@@ -0,0 +1,4 @@
+{
+	"title": "Components",
+	"pages": ["router.mdx", "route.mdx", "a.mdx", "navigate.mdx"]
+}

src/routes/reference/solid-router/components/navigate.mdx

@@ -0,0 +1,16 @@
+---
+title: Navigate
+---
+
+Solid Router provides a `Navigate` component that works similarly to `A`, but it will _immediately_ navigate to the provided path as soon as the component is rendered. It also uses the `href` prop, but you have the additional option of passing a function to `href` that returns a path to navigate to:
+
+```jsx
+function getPath({ navigate, location }) {
+	// navigate is the result of calling useNavigate(); location is the result of calling useLocation().
+	// You can use those to dynamically determine a path to navigate to
+	return "/some-path";
+}
+
+// Navigating to /redirect will redirect you to the result of getPath
+<Route path="/redirect" component={() => <Navigate href={getPath} />} />;
+```

src/routes/reference/solid-router/components/route.mdx

@@ -0,0 +1,13 @@
+---
+title: Route
+---
+
+The Component for defining Routes:
+
+| prop         | type            | description                                                       |
+| ------------ | --------------- | ----------------------------------------------------------------- |
+| path         | string          | Path partial for defining the route segment                       |
+| component    | `Component`     | Component that will be rendered for the matched segment           |
+| matchFilters | `MatchFilters`  | Additional constraints for matching against the route             |
+| children     | `JSX.Element`   | Nested `<Route>` definitions                                      |
+| load         | `RouteLoadFunc` | Function called during preload or when the route is navigated to. |

src/routes/reference/solid-router/components/router.mdx

@@ -0,0 +1,14 @@
+---
+title: Router
+---
+
+This is the main Router component for the browser.
+
+| prop          | type                                                     | description                                                                         |
+| ------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| children      | `JSX.Element`, `RouteDefinition`, or `RouteDefinition[]` | The route definitions                                                               |
+| root          | Component                                                | Top level layout component                                                          |
+| base          | string                                                   | Base url to use for matching routes                                                 |
+| actionBase    | string                                                   | Root url for server actions, default: `/_server`                                    |
+| preload       | boolean                                                  | Enables/disables preloads globally, default: `true`                                 |
+| explicitLinks | boolean                                                  | Disables all anchors being intercepted and instead requires `<A>`. default: `false` |

src/routes/reference/solid-router/data-apis/action.mdx

@@ -0,0 +1,87 @@
+---
+title: action
+---
+
+Actions are data mutations that can trigger invalidations and further routing. A list of prebuilt response helpers can be found below.
+
+```jsx
+import { action, revalidate, redirect } from "@solidjs/router"
+
+// anywhere
+const myAction = action(async (data) => {
+  await doMutation(data);
+  throw redirect("/", { revalidate: getUser.keyFor(data.id) }); // throw a response to do a redirect
+});
+
+// in component
+<form action={myAction} method="post" />
+
+//or
+<button type="submit" formaction={myAction}></button>
+```
+
+Actions only work with post requests, so make sure to put `method="post"` on your form.
+
+Sometimes it might be easier to deal with typed data instead of `FormData` and adding additional hidden fields. For that reason Actions have a with method. That works similar to `bind` which applies the arguments in order.
+
+Picture an action that deletes Todo Item:
+
+```js
+const deleteTodo = action(async (formData: FormData) => {
+  const id = Number(formData.get("id"))
+  await api.deleteTodo(id)
+})
+
+<form action={deleteTodo} method="post">
+  <input type="hidden" name="id" value={todo.id} />
+  <button type="submit">Delete</button>
+</form>
+```
+
+Instead with `with` you can write this:
+
+```js
+const deleteUser = action(api.deleteTodo)
+
+<form action={deleteTodo.with(todo.id)} method="post">
+  <button type="submit">Delete</button>
+</form>
+```
+
+### Notes of `<form>` implementation and SSR
+
+This requires stable references as you can only serialize a string as an attribute, and across SSR they'd need to match. The solution is providing a unique name.
+
+```jsx
+const myAction = action(async (args) => {}, "my-action");
+```
+
+## `useAction`
+
+Instead of forms you can use actions directly by wrapping them in a `useAction` primitive. This is how we get the router context.
+
+```jsx
+// in component
+const submit = useAction(myAction);
+submit(...args);
+```
+
+The outside of a form context you can use custom data instead of formData, and these helpers preserve types. However, even when used with server functions (in projects like SolidStart) this requires client side javascript and is not Progressive Enhancible like forms are.
+
+## `useSubmission`/`useSubmissions`
+
+Are used to injecting the optimistic updates while actions are in flight. They either return a single Submission(latest) or all that match with an optional filter function.
+
+```jsx
+type Submission<T, U> = {
+  input: T;
+  result: U;
+  error: any;
+  pending: boolean
+  clear: () => {}
+  retry: () => {}
+}
+
+const submissions = useSubmissions(action, (input) => filter(input));
+const submission = useSubmission(action, (input) => filter(input));
+```