preload ref updates

Author: LadyBluenotes

src/routes/solid-router/reference/preload-functions/preload.mdx

@@ -1,22 +1,17 @@
 ---
 title: preload
 use_cases: >-
-  route preloading, hover prefetch, parallel loading, performance optimization,
-  lazy routes, code splitting
+  route preload, route data, route definitions
 tags:
   - preload
-  - performance
   - routing
-  - prefetch
-  - lazy
-  - optimization
+  - data
 version: "1.0"
 description: >-
-  Preload route data and code in parallel to eliminate waterfalls. Enable hover
-  prefetching for instant page transitions.
+  preload is a route definition property for route data setup.
 ---
 
-`preload` is a route-definition property that runs during route preloading and rendering.
+`preload` is a [`Route`](/solid-router/reference/components/route) property for preparing route data before the route component renders or while a route is being preloaded.
 
 ## Import
 
@@ -27,81 +22,87 @@ import { Route } from "@solidjs/router";
 ## Type
 
 ```tsx
-type RoutePreloadFunc<T = unknown> = (args: RoutePreloadFuncArgs) => T;
+type Intent = "initial" | "native" | "navigate" | "preload";
 
 interface RoutePreloadFuncArgs {
 	params: Params;
 	location: Location;
-	intent: "initial" | "native" | "navigate" | "preload";
+	intent: Intent;
 }
+
+type RoutePreloadFunc<T = unknown> = (args: RoutePreloadFuncArgs) => T;
 ```
 
 ## Parameters
 
 ### `params`
 
 - **Type:** `Params`
+- **Required:** Yes
 
-An object containing the parameters for the matched route.
-It corresponds to the value returned by the [`useParams` primitive](/solid-router/reference/primitives/use-params).
+Route params for the matched route.
+The value has the same shape as [`useParams`](/solid-router/reference/primitives/use-params).
 
 ### `location`
 
 - **Type:** `Location`
+- **Required:** Yes
 
-The router's location object for the destination URL.
-It corresponds to the value returned by the [`useLocation` primitive](/solid-router/reference/primitives/use-location).
+[`Location`](/solid-router/reference/primitives/use-location) for the route being loaded or preloaded.
 
 ### `intent`
 
 - **Type:** `"initial" | "native" | "navigate" | "preload"`
+- **Required:** Yes
 
-A string indicating the context in which the function is called.
-
-| Value      | Meaning                                                            |
-| ---------- | ------------------------------------------------------------------ |
-| `preload`  | Preloading route code or data.                                     |
-| `navigate` | Client navigation to the route.                                    |
-| `native`   | Native history navigation, such as back or forward.                |
-| `initial`  | The first render for the current request or page load.             |
+Reason the router called the preload function, such as initial render, router navigation, native history navigation, or route preloading.
 
 ## Return value
 
-The value returned by `preload` is passed to the route's component as the `data` prop.
+- **Type:** `T`
 
-| Intent                              | Return value behavior                         |
-| ----------------------------------- | --------------------------------------------- |
-| `preload`                           | Ignored.                                      |
-| `initial`, `navigate`, or `native`  | Captured and passed to the component as `data`. |
+Returns the route data value.
+During route context creation, Solid Router passes this value to the matched route component as `props.data`.
 
 ## Behavior
 
-- During route preloading, the router calls `preload` for each matched route.
-- `load` is a deprecated alias for `preload` on route definitions.
-- Route component preloads run before the route's `preload` function when the component exposes a `.preload()` method.
+- During route context creation, Solid Router calls `preload` with the matched params, current location, and current router intent or `"initial"`.
+- Manual route preloading calls `preload` with `intent: "preload"` only when `preloadData` is truthy.
+- If a route definition has no `preload`, Solid Router uses the deprecated `load` property when one is present.
+- The route component's static `preload` method runs before the route-level `preload` function.
 
 ## Examples
 
+### Basic usage
+
 ```tsx
-import { Route, query, createAsync } from "@solidjs/router";
+import { Route, query } from "@solidjs/router";
 
-const getProductQuery = query(async (id: string) => {
-	// ... Fetches a product from the server.
+const getProduct = query(async (id: string) => {
+	const response = await fetch(`/api/products/${id}`);
+	return response.json();
 }, "product");
 
-function ProductPage(props) {
-	const product = createAsync(() => getProductQuery(props.params.id));
-
-	return <div>{product()?.title}</div>;
+function preloadProduct({ params }) {
+	void getProduct(params.id);
 }
 
-function preloadData({ params }) {
-	getProductQuery(params.id);
+function ProductPage(props) {
+	return <h1>Product {props.params.id}</h1>;
 }
 
-function ProductRoutes() {
+export default function ProductRoutes() {
 	return (
-		<Route path="/products/:id" component={ProductPage} preload={preloadData} />
+		<Route
+			path="/products/:id"
+			component={ProductPage}
+			preload={preloadProduct}
+		/>
 	);
 }
 ```
+
+## Related
+
+- [`Route`](/solid-router/reference/components/route)
+- [`usePreloadRoute`](/solid-router/reference/primitives/use-preload-route)