content: Expand notes on preloading data

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

@@ -461,8 +461,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) => {
@@ -509,8 +508,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](/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

@@ -16,24 +16,75 @@ description: >-
   performance. Components load on-demand and integrate with Suspense.
 ---
 
-```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 `preload()` function returned from calling the [`lazy()`](https://docs.solidjs.com/reference/component-apis/lazy) component API.
+
+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

@@ -15,10 +15,30 @@ description: >-
   prefetching route data before navigation in your SolidJS app.
 ---
 
-`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 |