content: Expand notes on preloading data (#1306)

Co-authored-by: Copilot <[email protected]>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
Co-authored-by: Eric L. Goldstein <[email protected]>
Co-authored-by: Sarah Gerrard <[email protected]>
Co-authored-by: Sarah <[email protected]>

Author: 5 people

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,81 @@ description: >-
   performance. Components load on-demand and integrate with Suspense.
 ---
 
-```ts
+The `lazy` helper wraps a dynamic import and returns a component that loads on demand.
+Lazy components accept the same props as their eager counterparts and integrate with `<Suspense>` boundaries.
+
+## Import
+
+```tsx
 import { lazy } from "solid-js"
-import type { Component } from "solid-js"
+```
+
+## Type
 
+```tsx
 function lazy<T extends Component<any>>(
-	fn: () => Promise<{ default: T }>
+  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>`
+## Parameters
+
+### `fn`
+
+- **Type:** `() => Promise<{ default: T }>`
+- **Required:** Yes
+
+Dynamic import that resolves to the component module, exposing the component as the `default` export.
+
+## Return value
+
+`lazy` returns a renderable component compatible with `T`.
+The component exposes a `preload()` method that resolves the underlying module.
+
+| Property | Type | Description |
+| -------- | ---- | ----------- |
+| `preload` | `() => Promise<T>` | Loads the module without rendering and returns the resolved component. |
+
+## Examples
+
+### Basic usage
+
+```tsx title="app.tsx"
+import { lazy } from "solid-js"
+
+const ComponentA = lazy(() => import("./ComponentA"))
+
+function App(props: { title: string }) {
+  return <ComponentA title={props.title} />
+}
+```
+
+### Preloading nested lazy components
 
 ```tsx
-// wrap import
-const ComponentA = lazy(() => import("./ComponentA"));
+import { lazy } from "solid-js"
+import type { Component } from "solid-js"
+
+const Nested = lazy(() => import("./Nested"))
 
-// use in JSX
-<ComponentA title={props.title} />
+const ComponentWithPreload = () => {
+  const [showNested, setShowNested] = createSignal(false)
+
+  return (
+	<div>
+	  <button
+        onMouseEnter={() => Nested.preload()}
+        onClick={() => setShowNested(true)}
+      >Preload Nested Component</button>
+      <Show when={showNested()}>
+	    <Nested />
+      </Show>
+	</div>
+  )
+}
 ```
+
+## See also
+
+- [`Suspense`](https://docs.solidjs.com/reference/component-apis/suspense)
+- [Router preloading guide](/solid-router/advanced-concepts/preloading)

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,44 @@
+---
+title: Preloading
+---
+
+Preloading smooths navigation by resolving route code and data before a user completes a transition.
+Solid Router listens for intent signals, such as hover and focus, and primes the matching route after a short delay to balance responsiveness and network cost.
+Understanding the timing and scope of this work lets you decide when to rely on the default behaviour and when to layer custom strategies.
+
+| user action | route behaviour |
+| ----------- | --------------- |
+| hover | waits roughly 20 ms before preloading |
+| focus | preloads immediately |
+
+## How Solid Router Detects Intent
+
+Anchors registered with Solid Router emit hover and focus events that feed a small scheduler.
+The router debounces the hover signal for 20ms to ignore incidental pointer passes while still reacting quickly to purposeful movement.
+When the delay elapses, the router loads the route module and runs its preload routine so that navigation has the assets it needs when the user commits.
+
+Route modules can export a [`preload`](/solid-router/reference/preload-functions/preload) function that receives params, search values, and router context.
+The function lets you seed caches, warm derived computations, or coordinate streaming behaviours without blocking the eventual render.
+
+> [!NOTE]
+> SSR invokes route `preload` functions during the initial server render and resumes them on the client during hydration.
+> Keep these functions pure so the hydrated client does not need to undo server work when it takes over.
+
+## Imperative Preloading Hooks
+
+Not every interaction funnels through an anchor element.
+The [`usePreloadRoute`](/solid-router/reference/primitives/use-preload-route) primitive exposes the same scheduling behaviour for imperative flows like flyout previews, timers, or observer driven experiences.
+
+This helper mirrors the router behaviour by resolving the module, optionally running the loader, and caching the result for the eventual navigation.
+Empirical tuning of delay values helps you avoid excessive prefetching in dense UIs while still keeping high intent interactions snappy.
+
+## Coordinating Nested Lazy Components
+
+Nested lazy components live outside the router hierarchy, so route preloading does not automatically warm them.
+The component API [`lazy()`](/reference/component-apis/lazy) exposes a `preload()` method that resolves a component without rendering it.
+Calling both the route preload and the nested component preload can keep large detail panels responsive when a user hovers or focuses on the entry point.
+
+Balancing manual preloading requires observing real user flows so you avoid prefetching large bundles that the user never requests.
+Profiling tools help you spot whether preloading reduces long tasks or simply shifts work earlier without net gains.
+
+To learn more about lazy loading components, see the [lazy documentation](/reference/component-apis/lazy#preloading-data-in-nested-lazy-components).

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 |