Merge pull request #3 from serkodev:feat/index-fallback

feat: index-fallback

docs/content/1.getting-started/3.configuration.md

@@ -48,7 +48,7 @@ The sync mode of the parallel route. Please read the [Parallel Routes > Sync Mod
 ##### `index`
 
 - Type: `string | undefined`
-- Default: `undefined`
+- Default: `/~index`
 
 The index page of the parallel route. Please read the [Parallel Routes > Fallback Mechanism](/routing/parallel-routes#fallback-mechanism) for more information.
 

docs/content/2.routing/1.parallel-routes.md

@@ -164,17 +164,17 @@ Here’s the fallback sequence of operations that occurs during navigation:
 **On initial page load:**
 
 1. Navigate if the current URL matches any routes in `~/pages`.
-2. Otherwise, redirect to `fallback.redirect` if it has been set in config.
-3. Otherwise, redirect to `index` if it has been set in config.
-4. Otherwise, render the `#not-found` slot if it has been set in `PlusParallelPage`.
-5. Otherwise, render the `#index` slot if it has been set in `PlusParallelPage`.
+2. Otherwise, try redirecting to [`fallback.redirect`](/getting-started/configuration#fallback) if it has been set in config.
+4. Otherwise, try rendering the `#not-found` slot if it has been set in [`PlusParallelPage`](/components/plus-parallel-page).
+3. Otherwise, try redirecting to `/~index` (or [`index`](/getting-started/configuration#index) set in config) if it can be resolved.
+5. Otherwise, try rendering the `#index` slot if it has been set in [`PlusParallelPage`](/components/plus-parallel-page).
 6. If none of the above conditions are met, leave the view empty.
 
 **On route navigate:**
 
 1. Navigate if the target URL matches any routes in `~/pages`.
-2. Otherwise, redirect to `fallback.redirect` if it has been set in config.
-3. Otherwise, render the `#not-found` slot if it has been set in `PlusParallelPage`.
+2. Otherwise, try redirecting to [`fallback.redirect`](/getting-started/configuration#fallback) if it has been set in config.
+3. Otherwise, try rendering the `#not-found` slot if it has been set in [`PlusParallelPage`](/components/plus-parallel-page).
 4. If none of the above conditions are met, keep the last successful view.
 
 ::alert{type="info"}

docs/layouts/parallel.vue

@@ -29,25 +29,7 @@ const relativePath = computed(() => {
             </NuxtLink>
           </div>
 
-          <PlusParallelPage name="left">
-            <template #index>
-              <TheBoundary label="layouts/parallel.vue > PlusParallelPage #index" class="p-4">
-                <p class="mb-4">
-                  This is the index view of the @left parallel routes.
-                </p>
-
-                <p class="my-4">
-                  The reason of rendering this view because when the page is init loaded but cannot find the match routes for <code class="text-nuxt">{{ relativePath }}</code>.
-                </p>
-
-                <p>
-                  Instead of render this <code>#index</code> slot, you can set the <NuxtLink to="/getting-started/configuration#index">
-                    <code class="text-nuxt">index</code>
-                  </NuxtLink> in config, so it will redirect to the index page of the parallel routes.
-                </p>
-              </TheBoundary>
-            </template>
-          </PlusParallelPage>
+          <PlusParallelPage name="left" />
         </div>
         <slot />
       </div>

docs/nuxt.config.ts

@@ -30,4 +30,14 @@ export default defineNuxtConfig({
   pagesPath: {
     basedPath: /examples\/[\w-]+\//,
   },
+
+  pagesPlus: {
+    parallelPages: {
+      left: {
+        // this config is for demo in docs only
+        // the index default value is '/~index' so usually you don't need to set it in your project
+        index: '/examples/parallel-routes/~index',
+      },
+    },
+  },
 })

docs/pages/examples/parallel-routes/@left/~index.vue

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+const relativePath = computed(() => {
+  return useRoute().path.replace(/^\/examples\/parallel-routes/, '') || '/'
+})
+</script>
+
+<template>
+  <TheBoundary label="$__PAGES_PATH__" class="p-4">
+    <p class="mb-4">
+      This is the index view of the @left parallel routes.
+    </p>
+
+    <p class="my-4">
+      The reason of rendering this view because when the page is init loaded but cannot find the match routes for <code class="text-nuxt">{{ relativePath }}</code>.
+    </p>
+
+    <p>
+      Instead of render this <code class="text-nuxt">/~index</code> path, you can set the <NuxtLink to="/getting-started/configuration#index">
+        <code class="text-nuxt underline">index</code>
+      </NuxtLink> in config, so it will redirect to the index page of the parallel routes.
+    </p>
+  </TheBoundary>
+</template>

examples/parallel-sidebar/pages/@left/~default.vue → examples/parallel-sidebar/pages/@left/~index.vue

@@ -1,5 +1,5 @@
 <template>
   <ExampleView label="$__PAGES_PATH__">
-    default fallback path
+    @left index fallback
   </ExampleView>
 </template>

examples/parallel-sidebar/pages/@main/~index.vue

@@ -0,0 +1,5 @@
+<template>
+  <ExampleView label="$__PAGES_PATH__">
+    @main index fallback
+  </ExampleView>
+</template>

src/runtime/parallel-router.ts

@@ -77,6 +77,7 @@ export default defineNuxtPlugin(async () => {
 async function createParallelRouter(name: string, routes: RouteRecord[], router: Router, parallelPageOptions: Partial<ParallelPageOptions>): Promise<ParallelRouter> {
   const options = defu(parallelPageOptions, {
     mode: 'sync',
+    index: '/~index',
     fallback: true,
   } satisfies ParallelPageOptions)
 
@@ -136,19 +137,23 @@ async function createParallelRouter(name: string, routes: RouteRecord[], router:
   }
 
   async function init() {
+    async function tryIndex() {
+      const pushIndex = options.index && tryPush(options.index)
+      if (pushIndex) {
+        await pushIndex
+      } else {
+        fallback.index = true
+      }
+    }
+
     if (options.mode === 'manual') {
-      if (options.index)
-        await parallelRouter.push(options.index)
+      await tryIndex()
     } else {
       const initSync = sync()
       if (initSync)
         await initSync
       else {
-        if (options.index) {
-          await parallelRouter.push(options.index)
-        } else {
-          fallback.index = true
-        }
+        await tryIndex()
       }
     }
   }

src/runtime/types.ts

@@ -2,7 +2,7 @@ export interface ParallelPageOptions {
   // default: 'sync'
   mode: 'sync' | 'sync-once' | 'manual'
 
-  // default: undefined
+  // default: '/~index'
   index?: string
 
   // default: true