Router section rewrite (#715)

Co-authored-by: root <root@TheGOAT>

Author: LadyBluenotes

.gitpod.yml

@@ -15,8 +15,8 @@ Lazy components trigger `<Suspense>`
 
 ```tsx
 // wrap import
-const ComponentA = lazy(() => import("./ComponentA"))
+const ComponentA = lazy(() => import("./ComponentA"));
 
 // use in JSX
-;<ComponentA title={props.title} />
+<ComponentA title={props.title} />
 ```

playwright.config.ts

@@ -1,11 +1,11 @@
 {
 	"title": "Store Utilities",
 	"pages": [
+		"create-mutable.mdx",
 		"create-store.mdx",
+		"modify-mutable.mdx",
 		"produce.mdx",
 		"reconcile.mdx",
-		"unwrap.mdx",
-		"create-mutable.mdx",
-		"modify-mutable.mdx"
+		"unwrap.mdx"
 	]
 }

sandbox.config.json

@@ -0,0 +1,4 @@
+{
+	"title": "Advanced Concepts",
+	"pages": ["lazy-loading.mdx"]
+}

src/routes/reference/component-apis/lazy.mdx

@@ -0,0 +1,27 @@
+---
+title: Lazy loading
+---
+
+Lazy loading allows you to load only the necessary resources when they are needed.
+This can be useful when you have a large application with a lot of routes and components, and you want to reduce the initial load time.
+
+In Solid Router, you can lazy load components using the `lazy` function from Solid:
+
+```jsx
+import { lazy } from "solid-js";
+import { Router, Route } from "solid-router";
+
+const Home = () => import("./Home");
+const Users = lazy(() => import("./Users"));
+
+const App = () => (
+  <Router>
+    <Route path="/" element={<Home />} />
+    <Route path="/users" element={<Users />} />
+  </Router>
+);
+```
+
+In the example above, the `Home` component is lazy loaded using the `lazy` function.
+The `lazy` function takes a function that returns a promise, which resolves to the component you want to load.
+When the route is matched, the component will be loaded and rendered.

src/routes/reference/store-utilities/data.json

@@ -2,64 +2,74 @@
 title: "Actions"
 ---
 
-To communicate with your server, you will need to use actions. 
-Actions are a way to submit data to your server and receive a response. 
-They are isomorphic, meaning they can run on the server or the client.
+When developing applications, it is common to need to communicate new information to the server based on user interactions.
+Actions are Solid Routers solution to this problem.
 
-One question you will likely have when developing any sort of app is "how do I communicate new information to my server?". 
-The user did something.
- What next? Solid Router's answer to this is _actions_.
+## What are actions?
 
-Actions give you the ability to specify an async action processing function and gives you elegant tools to help you easily manage and track submissions. Actions are isomorphic and represent a `POST` request.
+Actions are asynchronous processing functions that allow you to submit data to your server and receive a response.
+They are isomorphic, meaning they can run either on the server or the client, depending on what is needed.
+This flexibility makes actions a powerful tool for managing and tracking data submission.
 
-Actions are isomorphic. This means that a submission can be handled on the server _or_ the client, whichever is optimal. They represent the server component of an [HTML form](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form), and even help you use HTML forms to submit data.
+### How actions work
+
+Actions represent the server-side part of an [HTML form](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form).
+They handle submissions through POST requests, allowing you to easily use HTML forms to send data.
+
+When a user performs an action, such as submitting a form, the data is sent to the server for processing via an action.
+
+### Benefits of using actions
+
+1. **Isomorphic**: Since actions can run on both the server and client, you can optimize performance by choosing the best execution environment for your needs.
+2. **Asynchronous processing**: Actions handle data submissions asynchronously, ensuring that your application remains responsive.
+3. **Simplified data handling**: By using actions, the process of managing and tracking data submissions can be streamlined, reducing the complexity of your application.
 
 ## Creating actions
 
-Let's stop getting ahead of ourselves! First, let's create an action!
+To create an action, use the `action` function from the `@solidjs/router` package. 
+This function takes an asynchronous function as an argument and returns a new function that can be used to submit data.
 
-```tsx twoslash
+```tsx
 import { action, useAction } from "@solidjs/router";
 
 const echo = action(async (message: string) => {
-  // Imagine this is a call to fetch
+  // Simulates an asynchronous operation, such as an API call
   await new Promise((resolve, reject) => setTimeout(resolve, 1000));
   console.log(message);
 });
-
-export function MyComponent() {
-  const myEcho = useAction(echo);
-}
 ```
 
-This `echo` action will act as your backend, however you can substitute it for any API, provided you are ok with it running on the client. Typically, route actions are used with some sort of solution like fetch or GraphQL.
+In this example, the `echo` action simulates a fetch call with a 1 second delay before logging the message to the console.
+The `echo` action will act as a backend, however, it can be substituted for any API provided it can be run on the client.
+Typically, route actions are used with some sort of solution like fetch or GraphQL.
 
-These will return either a `Response` such as a redirect (we are not returning anything quite yet!) or any value. If you want to ensure the action only runs on the server for things like databases, you will want to use `"use server"`, introduced below.
+### Using actions
 
-Naturally, this action won't do anything quite yet. We still need to call it somewhere! For now, let's call it manually from some component using the submit function returned from `action`.
+To use the action, you can call it from within a component using `useAction`.
+This returns a function that can be called with the necessary arguments to trigger the action.
 
-```tsx twoslash
-import { action, useAction } from "@solidjs/router";
-
-const echo = action(async (message: string) => {
-  // Imagine this is a call to fetch
-  await new Promise((resolve, reject) => setTimeout(resolve, 1000));
-  console.log(message);
-});
+```tsx
+import { useAction } from "@solidjs/router";
 
 export function MyComponent() {
   const myEcho = useAction(echo);
-  myEcho("Hello from solid!");
+
+  myEcho("Hello from Solid!");
 }
 ```
 
-You should see `Hello from solid!` back in the console!
+In this component, `useAction` is used to get a reference to the `echo` action.
+The action is then called with the message `"Hello from Solid!"`, which will be logged to the console after a 1 second delay.
+
+### Returning data from actions
 
-### Returning from actions
+In many cases, after submitting data, the server sends some data back as well.
+This may be in the form of an error message if something has failed or the results of a successful operation.
+Anything returned from an action can be accessed using the reactive `action.result` property, where the value can change each time you submit your action.
 
-In many cases, after submitting data the server sends some data back as well. Usually an error message if something failed. Anything returned from your action function can be accessed using the reactive `action.result` property. The value of this property can change each time you submit your action.
+To access the action's result, you must pass the action to `useSubmission`:
 
-```tsx twoslash
+```tsx {8,14}
 import { action, useAction, useSubmission } from "@solidjs/router";
 
 const echo = action(async (message: string) => {
@@ -70,35 +80,46 @@ const echo = action(async (message: string) => {
 export function MyComponent() {
   const myEcho = useAction(echo);
   const echoing = useSubmission(echo);
+
   myEcho("Hello from solid!");
+
   setTimeout(() => myEcho("This is a second submission!"), 1500);
+
   return <p>{echoing.result}</p>;
 }
 ```
 
-While this method of using actions works, it leaves the implementation details of how you trigger `echo` up to you. When handling explicit user input, it's better to use a `form` for a multitude of reasons.
+Using `useSubmission` leaves the implementation details of how you trigger `echo` up to you.
+Whe handling user inputs, for example, it is better to use a `form` for a multitude of reasons.
 
 ## Using forms to submit data
 
-We highly recommend using HTML forms as your method to submit data with actions. HTML forms can be used even before JavaScript loads, leading to instantly interactive applications.
+When submitting data with actions, it is recommended to use HTML forms.
+These forms can be used prior to JavaSCript loading, which creates instantly interactive applications.
+This also inherently provides accessibility benefits, saving the time of designing a custom UI library that may not have these benefits.
 
-They have the added benefit of implicit accessibility. They can save you valuable time that would have otherwise been spent designing a UI library that will never have the aforementioned benefits.
+When using forms to submit actions, the first argument passed to your action function is an instance of [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData).
+To use actions with forms, pass the action to the `action` property of your form.
+This creates progressively enhanced forms that work even when JavaScript is disabled.
 
-When forms are used to submit actions, the first argument is an instance of [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData). To write a form using actions, pass the action to the action property of your form. You can then walk away with amazing, progressively enhanced forms!
+If you do not return a `Response` from your action, the user will stay on the same page and responses will be re-triggered.
+Using a `redirect` can tell the browser to navigate to a new page.
 
-If you don't return a `Response` from your action, the user will stay on the same page and your resources will be re-triggered. You can also throw a `redirect` to tell the browser to navigate.
 
-```tsx twoslash
+```tsx
 import { action, redirect } from "@solidjs/router";
 
 const isAdmin = action(async (formData: FormData) => {
   await new Promise((resolve, reject) => setTimeout(resolve, 1000));
+
   const username = formData.get("username");
+
   if (username === "admin") throw redirect("/admin");
   return new Error("Invalid username");
 });
 
 export function MyComponent() {
+
   return (
     <form action={isAdmin} method="post">
       <label for="username">Username:</label>
@@ -111,6 +132,8 @@ export function MyComponent() {
 
 ## Error handling
 
-We strongly recommend with actions to "return" errors rather than throwing them. This can help with typing of submissions you'd use with `useSubmission`. This is important especially for handling progressive enhancement where no JS is present in the client so that we can use the error declaratively to render the updated page on the server.
+Rather than throwing errors, it is recommended to return them from actions.
+This helps with the typing of submissions that would be used with `useSubmission`.
+This is important when handling progressive enhancement where no JavaScript is present in the client, so that errors can be used declaratively to render the updated page on the server.
 
-Additionally when using Server Actions it is good practice to try to handle errors on the server so that you can sanitize error messages.
+Additionally, when using server actions, it is good practice to handle errors on the server to sanitize error messages.