content: Expand notes on preloading data

src/routes/guides/routing-and-navigation.mdx

@@ -446,8 +446,7 @@ The preload function is then passed in the `<Route>` definition:
 You can export preload functions and data wrappers that correspond to routes from a dedicated `[route].data.js` or `[route].data.ts` file.
 This pattern provides a way to import the data function without loading anything else.
 
-```jsx
-// src/pages/users/[id].data.js
+```tsx title="src/pages/users/[id].data.js"
 import { query } from "@solidjs/router";
 
 export const getUser = query(async (id) => {
@@ -494,8 +493,7 @@ render(
 `[id].jsx` contains the component that gets rendered.
 When you wrap the function within [`createAsync`](/solid-router/reference/data-apis/create-async) with the imported function, it will yield [a signal](/routes/concepts/signals) once the anticipated promise resolves.
 
-```jsx
-// [id].jsx
+```tsx title="[id].tsx"
 import { createAsync } from "@solidjs/router";
 import { getUser } from "./[id].data";
 

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

@@ -2,24 +2,75 @@
 title: lazy
 ---
 
-```ts
+Used to lazy load components to allow for code splitting. 
+Components are not loaded until rendered or manually preloaded. 
+
+```tsx title="app.tsx"
+import { lazy } from "solid-js"
+
+const ComponentA = lazy(() => import("./ComponentA"));
+
+function App(props: { title: string }) {
+ return (
+<ComponentA title={props.title} />
+)
+}
+```
+
+Lazy loaded components can be used the same as its statically imported counterpart, receiving props etc. 
+Lazy components trigger `<Suspense>`
+
+## Preloading data in Nested Lazy Components
+
+Top-level lazy components will automatically be preloaded as well as their preload functions.
+However, nested lazy components will not be preloaded automatically because they are not part of the route hierarchy.
+To preload such components, you can use the `preload` method exposed on the lazy component.
+
+```tsx title="component-with-preload.tsx"
 import { lazy } from "solid-js"
 import type { Component } from "solid-js"
 
+const Nested = lazy(() => import("./Nested"))
+
+const ComponentWithPreload: Component = () => {
+ // preload Nested component when needed
+ async function handlePreload() {
+await Nested.preload()
+ }
+
+ return (
+<div>
+ <button onClick={handlePreload}>Preload Nested Component</button>
+ <Nested />
+</div>
+ )
+}
+
+```
+
+## Type Signature
+
+```tsx
 function lazy<T extends Component<any>>(
 fn: () => Promise<{ default: T }>
 ): T & { preload: () => Promise<T> }
 ```
 
-Used to lazy load components to allow for code splitting. 
-Components are not loaded until rendered. 
-Lazy loaded components can be used the same as its statically imported counterpart, receiving props etc. 
-Lazy components trigger `<Suspense>`
+### Type Parameters
 
-```tsx
-// wrap import
-const ComponentA = lazy(() => import("./ComponentA"));
+| Name | Constraint | Description |
+| ---- | ---------- | ----------- |
+| `T` | `Component<any>` | The component type that will be lazily loaded (including its props).
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `fn` | `() => Promise<{ default: T }>` | Yes | A function that returns a dynamic import resolving to the component as the `default` export. |
+
+### Returns
+
+| Type | Description |
+| ---- | ----------- |
+| `T & { preload: () => Promise<T> }` | A renderable component compatible with `T` that also exposes a `preload()` method to eagerly load the module. |
 
-// use in JSX
-<ComponentA title={props.title} />
-```

src/routes/solid-router/advanced-concepts/data.json

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

src/routes/solid-router/advanced-concepts/preloading.mdx

@@ -0,0 +1,24 @@
+---
+title: Preloading
+---
+
+Anchors in Solid Router will preload routes by default on link hover/focus to improve perceived performance.
+
+To enhance preloading, you can define the `preload` function on your route definition.
+When on a [SolidStart](/solid-start) application, this function can also run on the server during the initial page load to start fetching data before rendering. When in a Single-Page Application (SPA), it will load the route's component and its `preload` function when the user hovers or focuses on a link.
+
+| user action | route behavior |
+| ----------- | -------------------------------------- |
+| hover | with a 300ms delay to avoid excessive preloading |
+| focus | immediately |
+
+## Imperative Preloading
+
+You can also use the [`usePreloadRoute`](/solid-router/reference/primitives/use-preload-route) helper to preload routes programmatically in response to events other than link hover/focus, such as button clicks or timers.
+This helper will load only the route's component by default, but it can receive a configuration object to also load the data.
+
+## Preloading and Lazy Loading
+
+When a route has nested lazy components, such components will not be part of the route hierarchy, so they **will not** be preloaded with the route. To preload such components, you can use the [`usePreloadRoute`](/solid-router/reference/primitives/use-preload-route) helper in the parent component to load them when needed.
+
+To learn more about lazy loading components, see the [`lazy`](/reference/component-apis/lazy#preloading-data-in-nested-lazy-components) documentation.

src/routes/solid-router/reference/primitives/use-preload-route.mdx

@@ -2,10 +2,30 @@
 title: usePreloadRoute
 ---
 
-`usePreloadRoute` returns a function that can be used to preload a route manually. This is what happens automatically with link hovering and similar focus based behavior, but it is available here as an API.
+`usePreloadRoute` returns a function that can be used to preload a route manually.
 
-```js
+```ts
 const preload = usePreloadRoute();
 
 preload(`/users/settings`, { preloadData: true });
 ```
+
+## Usage
+
+Routes are preloaded by default within Solid Router contexts.
+This helper is useful when you want to preload a route in response to some other event, such as a button click or a timer.
+
+## Type Signature
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+| --------- | -------- | -------- | ------------------------------------ |
+| `to` | `To` | Yes | The route path to preload |
+| `options` | `object` | No | Configuration options for preloading |
+
+### Options
+
+| Option | Type | Default | Description |
+| ------------- | --------- | ------- | ------------------------------------------------------------------- |
+| `preloadData` | `boolean` | `false` | Whether to preload the route's data in addition to the route itself |