docs: add additional information about NuxtPage (#30781)

docs/3.api/1.components/2.nuxt-page.md

@@ -11,26 +11,45 @@ links:
 `<NuxtPage>` is a built-in component that comes with Nuxt. It lets you display top-level or nested pages located in the [`pages/`](/docs/guide/directory-structure/pages) directory.
 
 ::note
-`<NuxtPage>` is a wrapper around [`<RouterView>`](https://router.vuejs.org/api/interfaces/RouterViewProps.html#interface-routerviewprops) component from Vue Router. :br
+`<NuxtPage>` is a wrapper around [`<RouterView>`](https://router.vuejs.org/api/interfaces/RouterViewProps.html#interface-routerviewprops) from Vue Router. It should be used instead of `<RouterView>` because the former takes additional care of internal states. Otherwise, `useRoute()` may return incorrect paths.
-It accepts same `name` and `route` props.
 ::
 
+`<NuxtPage>` includes the following components:
+
+```vue
+<template>
+  <RouterView #default="{ Component }">
+    <!-- Optional, when using transitions -->
+    <Transition>
+      <!-- Optional, when using keep-alive -->
+      <KeepAlive>
+        <Suspense>
+          <component :is="Component" />
+        </Suspense>
+      </KeepAlive>
+    </Transition>
+  </RouterView>
+</template>
+```
+
+By default, Nuxt does not enable `<Transition>` and `<KeepAlive>`. You can enable them in the nuxt.config file or by setting the `transition` and `keepalive` properties on `<NuxtPage>`. If you want to define a specific page, you can set it in `definePageMeta` in the page component.
+
 ::warning
-`<NuxtPage>` should be used instead of `<RouterView>` as the former takes additional care on internal states. Otherwise, `useRoute()` may return incorrect paths.
+If you enable `<Transition>` in your page component, ensure that the page has a single root element.
 ::
 
 ## Props
 
-- `name`: tells `RouterView` to render the component with the corresponding name in the matched route record's components option.
+- `name`: tells `<RouterView>` to render the component with the corresponding name in the matched route record's components option.
   - type: `string`
 - `route`: route location that has all of its components resolved.
   - type: `RouteLocationNormalized`
 - `pageKey`: control when the `NuxtPage` component is re-rendered.
   - type: `string` or `function`
 - `transition`: define global transitions for all pages rendered with the `NuxtPage` component.
-  - type: `boolean` or `TransitionProps`
+  - type: `boolean` or [`TransitionProps`](https://vuejs.org/api/built-in-components#transition)
 - `keepalive`: control state preservation of pages rendered with the `NuxtPage` component.
-  - type: `boolean` or `KeepAliveProps`
+  - type: `boolean` or [`KeepAliveProps`](https://vuejs.org/api/built-in-components#keepalive)
 
 ::tip
 Nuxt automatically resolves the `name` and `route` by scanning and rendering all Vue component files found in the `/pages` directory.
@@ -38,7 +57,7 @@ Nuxt automatically resolves the `name` and `route` by scanning and rendering all
 
 ## Example
 
-For example, passing `static` key, `NuxtPage` component is rendered only once when it is mounted.
+For example, if you pass a key that never changes, the `<NuxtPage>` component will be rendered only once - when it is first mounted.
 
 ```vue [app.vue]
 <template>
@@ -100,14 +119,32 @@ defineExpose({
 
 ## Custom Props
 
-In addition, `<NuxtPage>` also accepts custom props that you may need to pass further down the hierarchy.
+`<NuxtPage>` also accepts custom props that you may need to pass further down the hierarchy.
 
-These custom props are accessible via `attrs` in the Nuxt app.
+For example, in the below example, the value of `foobar` will be passed to the `NuxtPage` component and then to the page components.
 
-```html
+```vue [app.vue]
+<template>
   <NuxtPage :foobar="123" />
+</template>
 ```
 
-For example, in the above example, the value of `foobar` will be available using `$attrs.foobar` in the template or `useAttrs().foobar` in `<script setup>`.
+We can access the `foobar` prop in the page component:
+
+```vue [pages/page.vue]
+<script setup lang="ts">
+const props = defineProps<{ foobar: number }>()
+
+console.log(props.foobar) // Outputs: 123
+```
+
+If you have not defined the prop with `defineProps`, any props passed down to `NuxtPage` can still be accessed directly from the page `attrs`:
+
+```vue [pages/page.vue]
+<script setup lang="ts">
+const attrs = useAttrs()
+console.log(attrs.foobar) // Outputs: 123
+</script>
+```
 
 :read-more{to="/docs/guide/directory-structure/pages"}