kiru 0.53.0 → 0.54.0-preview.1

package/src/router/fileRouterController.ts

@@ -2,9 +2,15 @@ import { Signal } from "../signals/base.js"
 import { watch } from "../signals/watch.js"
 import { __DEV__ } from "../env.js"
 import { flushSync, nextIdle } from "../scheduler.js"
+import { toArray } from "../utils/format.js"
 import { ReloadOptions, type FileRouterContextType } from "./context.js"
 import { FileRouterDataLoadError } from "./errors.js"
-import { fileRouterInstance, fileRouterRoute, routerCache } from "./globals.js"
+import {
+  fileRouterInstance,
+  fileRouterRoute,
+  requestContext,
+  routerCache,
+} from "./globals.js"
 import type {
   FileRouterConfig,
   PageConfig,
@@ -17,17 +23,22 @@ import type {
   CurrentPage,
   DevtoolsInterface,
   FormattedViteImportMap,
+  GuardModule,
   PageModule,
   ViteImportMap,
 } from "./types.internal.js"
 import {
   formatViteImportMap,
-  matchLayouts,
+  matchModules,
   matchRoute,
   match404Route,
   normalizePrefixPath,
   parseQuery,
   wrapWithLayouts,
+  runAfterEachGuards,
+  runBeforeEachGuards,
+  runBeforeEnterHooks,
+  runBeforeLeaveHooks,
 } from "./utils/index.js"
 import { RouterCache, type CacheKey } from "./cache.js"
 import { scrollStack } from "./scrollStack.js"
@@ -36,6 +47,19 @@ interface PageConfigWithLoader<T = unknown> extends PageConfig {
   loader: PageDataLoaderConfig<T>
 }
 
+interface LoadRouteOptions {
+  path?: string
+  transition?: boolean
+  isStatic404?: boolean
+  onPaint?: () => void
+}
+
+let transitionId = 0
+let currentTransition = null as null | {
+  transition: ViewTransition
+  id: number
+}
+
 export class FileRouterController {
   public contextValue: FileRouterContextType
   public devtools?: DevtoolsInterface
@@ -55,6 +79,7 @@ export class FileRouterController {
   private historyIndex: number
   private layouts: FormattedViteImportMap
   private pages: FormattedViteImportMap<PageModule>
+  private guards: FormattedViteImportMap<GuardModule>
   private pageRouteToConfig?: Map<string, PageConfig>
   private state: RouterState
 
@@ -68,6 +93,7 @@ export class FileRouterController {
     this.historyIndex = 0
     this.layouts = {}
     this.pages = {}
+    this.guards = {}
     this.state = {
       pathname: window.location.pathname,
       hash: window.location.hash,
@@ -79,7 +105,7 @@ export class FileRouterController {
     this.contextValue = {
       invalidate: async (...paths: string[]) => {
         if (this.invalidate(...paths)) {
-          return this.loadRoute(void 0, void 0, true)
+          return this.loadRoute()
         }
       },
       get state() {
@@ -91,7 +117,7 @@ export class FileRouterController {
         if (options?.invalidate ?? true) {
           this.invalidate(this.state.pathname)
         }
-        return this.loadRoute(void 0, void 0, options?.transition)
+        return this.loadRoute({ transition: options?.transition })
       },
       setQuery: this.setQuery.bind(this),
       setHash: this.setHash.bind(this),
@@ -112,12 +138,11 @@ export class FileRouterController {
         if (curPage?.route === existing.route && loader) {
           const p = this.currentPageProps.value
           const transition =
-            (loader.mode !== "static" && loader.transition) ??
-            this.enableTransitions
+            (!loader.static && loader.transition) ?? this.enableTransitions
 
           // Check cache first if caching is enabled
           let cachedData = null
-          if (loader.mode !== "static" && loader.cache) {
+          if (!loader.static && loader.cache) {
             const cacheKey: CacheKey = {
               path: this.state.pathname,
               params: this.state.params,
@@ -134,9 +159,11 @@ export class FileRouterController {
               error: null,
               loading: false,
             }
-            handleStateTransition(this.state.signal, transition, () => {
-              this.currentPageProps.value = props
-            })
+            handleStateTransition(
+              transition,
+              transitionId,
+              () => (this.currentPageProps.value = props)
+            )
           } else {
             // No cached data - show loading state and load data
             const props = {
@@ -145,13 +172,14 @@ export class FileRouterController {
               data: null,
               error: null,
             }
-            handleStateTransition(this.state.signal, transition, () => {
-              this.currentPageProps.value = props
-            })
+            handleStateTransition(
+              transition,
+              transitionId,
+              () => (this.currentPageProps.value = props)
+            )
 
             this.loadRouteData(
               config as PageConfigWithLoader,
-              props,
               this.state,
               transition
             )
@@ -187,6 +215,7 @@ export class FileRouterController {
     const {
       pages,
       layouts,
+      guards,
       dir = "/pages",
       baseUrl = "/",
       transition,
@@ -198,12 +227,38 @@ export class FileRouterController {
       normalizePrefixPath(baseUrl),
     ]
 
-    if (preloaded) {
+    if (!preloaded) {
+      this.pages = formatViteImportMap(
+        pages as ViteImportMap,
+        normalizedDir,
+        normalizedBaseUrl
+      )
+
+      this.layouts = formatViteImportMap(
+        layouts as ViteImportMap,
+        normalizedDir,
+        normalizedBaseUrl
+      )
+      this.guards = !guards
+        ? {}
+        : (formatViteImportMap(
+            guards as ViteImportMap,
+            normalizedDir,
+            normalizedBaseUrl
+          ) as unknown as FormattedViteImportMap<GuardModule>)
+
+      if (__DEV__) {
+        validateRoutes(this.pages)
+      }
+      this.loadRoute()
+    } else {
       const {
         pages,
         layouts,
+        guards,
         page,
         pageProps,
+        pagePropsPromise,
         pageLayouts,
         route,
         params,
@@ -226,57 +281,49 @@ export class FileRouterController {
       this.currentLayouts.value = pageLayouts.map((l) => l.default)
       this.pages = pages
       this.layouts = layouts
+      this.guards = (guards ??
+        {}) as unknown as FormattedViteImportMap<GuardModule>
       if (__DEV__) {
+        validateRoutes(this.pages)
         if (page.config) {
           this.dev_onPageConfigDefined!(route, page.config)
         }
       }
-      if (__DEV__) {
-        validateRoutes(this.pages)
-      }
+
       const loader = page.config?.loader
-      if (
+      const transition =
+        (!loader?.static && loader?.transition) ?? this.enableTransitions
+
+      if (loader && pagePropsPromise) {
+        const prevState = this.state
+        pagePropsPromise.then(({ data, error }) => {
+          if (this.state !== prevState) return
+
+          handleStateTransition(
+            transition,
+            transitionId,
+            () =>
+              (this.currentPageProps.value = { loading: false, data, error })
+          )
+        })
+      } else if (
         loader &&
-        ((loader.mode !== "static" && pageProps.loading === true) || __DEV__)
+        ((!loader.static && pageProps.loading === true) || __DEV__)
       ) {
         if (cacheData === null) {
-          this.loadRouteData(
-            page.config as PageConfigWithLoader,
-            pageProps,
-            this.state
-          )
+          this.loadRouteData(page.config as PageConfigWithLoader, this.state)
         } else {
           nextIdle(() => {
-            const props = {
-              ...pageProps,
-              data: cacheData.value,
-              error: null,
-              loading: false,
-            }
-            // @ts-ignore
-            const transition = loader.transition ?? this.enableTransitions
-            handleStateTransition(this.state.signal, transition, () => {
-              this.currentPageProps.value = props
+            handleStateTransition(transition, transitionId, () => {
+              this.currentPageProps.value = {
+                data: cacheData.value,
+                error: null,
+                loading: false,
+              }
             })
           })
         }
       }
-    } else {
-      this.pages = formatViteImportMap(
-        pages as ViteImportMap,
-        normalizedDir,
-        normalizedBaseUrl
-      )
-
-      this.layouts = formatViteImportMap(
-        layouts as ViteImportMap,
-        normalizedDir,
-        normalizedBaseUrl
-      )
-      if (__DEV__) {
-        validateRoutes(this.pages)
-      }
-      this.loadRoute()
     }
 
     window.history.scrollRestoration = "manual"
@@ -315,22 +362,74 @@ export class FileRouterController {
       window.history.scrollRestoration = "auto"
     })
 
+    let ignorePopState = false
+
     window.addEventListener("popstate", (e) => {
       e.preventDefault()
+
+      if (
+        !ignorePopState &&
+        this.onBeforeLeave(window.location.pathname) === false
+      ) {
+        ignorePopState = true
+        if (e.state !== null) {
+          if (e.state.index > this.historyIndex) {
+            window.history.go(-1)
+          } else if (e.state.index < this.historyIndex) {
+            window.history.go(1)
+          }
+        }
+        return
+      }
+      if (ignorePopState) {
+        ignorePopState = false
+        return
+      }
+
       scrollStack.replace(this.historyIndex, window.scrollX, window.scrollY)
 
-      this.loadRoute().then(() => {
-        if (e.state != null) {
+      // prep 'on painted' callback for scroll-to-offset action
+      // this will fire once the page has rendered but before (loader?) kicks off.
+      let onPaint
+      if (e.state != null) {
+        onPaint = () => {
           this.historyIndex = e.state.index
           const offset = scrollStack.getItem(e.state.index)
           if (offset !== undefined) {
             window.scrollTo(...offset)
           }
         }
-      })
+      }
+
+      this.loadRoute({ onPaint })
     })
   }
 
+  private onBeforeLeave(to: string) {
+    const currentPage = this.currentPage.peek()
+    if (!currentPage) {
+      return true
+    }
+
+    let config = currentPage.config ?? ({} as PageConfig)
+    if (__DEV__) {
+      if (this.pageRouteToConfig?.has(currentPage.route)) {
+        config = this.pageRouteToConfig.get(currentPage.route)!
+      }
+    }
+
+    const onBeforeLeave = config.hooks?.onBeforeLeave
+    if (onBeforeLeave) {
+      return runBeforeLeaveHooks(
+        toArray(onBeforeLeave),
+        { ...requestContext.current },
+        to,
+        this.state.pathname
+      )
+    }
+    return true
+  }
+
   public getChildren() {
     const page = this.currentPage.value
     if (!page) return null
@@ -351,12 +450,14 @@ export class FileRouterController {
     fileRouterInstance.current = null
   }
 
-  private async loadRoute(
-    path: string = window.location.pathname,
-    props: Record<string, unknown> = {},
-    enableTransition = this.enableTransitions,
-    isStatic404 = false
-  ): Promise<void> {
+  private async loadRoute(options?: LoadRouteOptions): Promise<void> {
+    const {
+      transition: enableTransition = this.enableTransitions,
+      isStatic404 = false,
+      path = window.location.pathname,
+      onPaint,
+    } = options ?? {}
+
     this.abortController?.abort()
     const signal = (this.abortController = new AbortController()).signal
 
@@ -381,10 +482,38 @@ See https://kirujs.dev/docs/api/file-router#404 for more information.`
 
       const { route, pageEntry, params, routeSegments } = routeMatch
 
+      // Apply beforeEach guards before loading route
+      const guardEntries = matchModules(
+        this.guards as unknown as FormattedViteImportMap,
+        routeSegments
+      )
+      const guardModules = await Promise.all(
+        guardEntries.map(
+          (entry) => entry.load() as unknown as Promise<GuardModule>
+        )
+      )
+
+      const fromPath = this.state.pathname
+      const redirectPath = await runBeforeEachGuards(
+        guardModules,
+        { ...requestContext.current },
+        path,
+        fromPath
+      )
+
+      // If redirect was requested, navigate to that path instead
+      if (redirectPath !== null) {
+        this.state.pathname = path
+        return this.navigate(redirectPath, {
+          replace: true,
+          transition: enableTransition,
+        })
+      }
+
       fileRouterRoute.current = route
       const pagePromise = pageEntry.load()
 
-      const layoutPromises = matchLayouts(this.layouts, routeSegments).map(
+      const layoutPromises = matchModules(this.layouts, routeSegments).map(
         (layoutEntry) => layoutEntry.load()
       )
 
@@ -418,62 +547,76 @@ See https://kirujs.dev/docs/api/file-router#404 for more information.`
         }
       }
 
-      const { loader } = config
+      const { loader, hooks } = config
 
-      if (loader) {
-        if (loader.mode !== "static" || __DEV__) {
-          // Check cache first if caching is enabled
-          let cachedData = null
-          if (loader.mode !== "static" && loader.cache) {
-            const cacheKey: CacheKey = {
-              path: routerState.pathname,
-              params: routerState.params,
-              query: routerState.query,
-            }
-            cachedData = routerCache.current!.get(cacheKey, loader.cache)
-          }
+      if (hooks?.onBeforeEnter) {
+        const redirectPath = await runBeforeEnterHooks(
+          toArray(hooks.onBeforeEnter),
+          requestContext,
+          path,
+          fromPath
+        )
+        if (redirectPath !== null) {
+          this.state.pathname = path
+          return this.navigate(redirectPath, {
+            replace: true,
+            transition: enableTransition,
+          })
+        }
+      }
 
-          if (cachedData !== null) {
-            // Use cached data immediately - no loading state needed
-            props = {
-              ...props,
-              data: cachedData.value,
-              error: null,
-              loading: false,
-            } satisfies PageProps<PageConfig<unknown>>
-          } else {
-            // No cached data - show loading state and load data
-            props = {
-              ...props,
-              loading: true,
+      let props: Record<string, unknown> = {}
+      if (!!loader) {
+        props = {
+          data: null,
+          error: null,
+          loading: true,
+        }
+      }
+
+      if (loader?.static && !__DEV__) {
+        const staticProps = page.__KIRU_STATIC_PROPS__?.[path]
+        if (!staticProps) {
+          // 404
+          return this.loadRoute({
+            path,
+            transition: enableTransition,
+            isStatic404: true,
+          })
+        }
+        const { data, error } = staticProps
+        props = error
+          ? {
               data: null,
+              error: new FileRouterDataLoadError(error),
+              loading: false,
+            }
+          : {
+              data: data,
               error: null,
-            } satisfies PageProps<PageConfig<unknown>>
-
-            this.loadRouteData(
-              config as PageConfigWithLoader,
-              props,
-              routerState,
-              enableTransition
-            )
-          }
-        } else {
-          const staticProps = page.__KIRU_STATIC_PROPS__?.[path]
-          if (!staticProps) {
-            return this.loadRoute(path, props, enableTransition, true)
-          }
+              loading: false,
+            }
+      } else if (!loader?.static && loader?.cache) {
+        const cacheKey: CacheKey = {
+          path: routerState.pathname,
+          params: routerState.params,
+          query: routerState.query,
+        }
+        const cachedData = routerCache.current!.get(cacheKey, loader.cache)
 
-          const { data, error } = staticProps
+        if (cachedData !== null) {
           props = {
-            ...props,
-            data: data,
-            error: error ? new FileRouterDataLoadError(error) : null,
+            data: cachedData.value,
+            error: null,
             loading: false,
-          } as PageProps<PageConfig<unknown>>
+          } satisfies PageProps<PageConfig<unknown>>
         }
       }
 
-      return handleStateTransition(signal, enableTransition, () => {
+      // loader transition must use the same id as page transition in order to prevent skipping it.
+      let tId = transitionId++
+
+      return await handleStateTransition(enableTransition, tId, () => {
         this.state = routerState
         this.currentPage.value = {
           component: page.default,
@@ -484,6 +627,25 @@ See https://kirujs.dev/docs/api/file-router#404 for more information.`
         this.currentLayouts.value = layouts
           .filter((m) => typeof m.default === "function")
           .map((m) => m.default)
+
+        nextIdle(() => {
+          runAfterEachGuards(
+            guardModules,
+            { ...requestContext.current },
+            path,
+            fromPath
+          )
+          if (props.loading) {
+            this.loadRouteData(
+              config as PageConfigWithLoader,
+              routerState,
+              enableTransition,
+              tId
+            ).then(() => signal.aborted || onPaint?.())
+          } else {
+            onPaint?.()
+          }
+        })
       })
     } catch (error) {
       console.error("[kiru/router]: Failed to load route component:", error)
@@ -493,19 +655,19 @@ See https://kirujs.dev/docs/api/file-router#404 for more information.`
 
   private async loadRouteData(
     config: PageConfigWithLoader,
-    props: Record<string, unknown>,
     routerState: RouterState,
-    enableTransition = this.enableTransitions
+    enableTransition = this.enableTransitions,
+    id = transitionId
   ) {
     const { loader } = config
 
     // Load data from loader (cache check is now done earlier in loadRoute)
-    loader
-      .load(routerState)
+    return loader
+      .load({ ...routerState, context: { ...requestContext.current } })
       .then(
         (data) => {
           // Cache the data if caching is enabled
-          if (loader.mode !== "static" && loader.cache) {
+          if (!loader.static && loader.cache) {
             const cacheKey: CacheKey = {
               path: routerState.pathname,
               params: routerState.params,
@@ -531,14 +693,13 @@ See https://kirujs.dev/docs/api/file-router#404 for more information.`
         if (routerState.signal.aborted) return
 
         const transition =
-          (loader.mode !== "static" && loader.transition) ?? enableTransition
+          (!loader.static && loader.transition) ?? enableTransition
 
-        handleStateTransition(routerState.signal, transition, () => {
-          this.currentPageProps.value = {
-            ...props,
-            ...state,
-          } satisfies PageProps<PageConfig<unknown>>
-        })
+        return handleStateTransition(
+          transition,
+          id,
+          () => (this.currentPageProps.value = state)
+        )
       })
   }
 
@@ -566,17 +727,17 @@ See https://kirujs.dev/docs/api/file-router#404 for more information.`
     const url = new URL(path, "http://localhost")
     const { hash: nextHash, pathname: nextPath } = url
     const { hash: prevHash, pathname: prevPath } = this.state
-    if (nextHash === prevHash && nextPath === prevPath) {
+    if (
+      (nextHash === prevHash && nextPath === prevPath) ||
+      this.onBeforeLeave(prevPath) === false
+    ) {
       return
     }
 
     this.updateHistoryState(path, options)
 
-    this.loadRoute(
-      void 0,
-      void 0,
-      options?.transition ?? this.enableTransitions
-    ).then(() => {
+    const transition = options?.transition ?? this.enableTransitions
+    this.loadRoute({ transition }).then(() => {
       if (nextHash !== prevHash) {
         window.dispatchEvent(new HashChangeEvent("hashchange"))
       }
@@ -603,7 +764,7 @@ See https://kirujs.dev/docs/api/file-router#404 for more information.`
       const { pageEntry, route } = routeMatch
       fileRouterRoute.current = route
       const pagePromise = pageEntry.load()
-      const layoutPromises = matchLayouts(this.layouts, route.split("/")).map(
+      const layoutPromises = matchModules(this.layouts, route.split("/")).map(
         (layoutEntry) => layoutEntry.load()
       )
       await Promise.all([pagePromise, ...layoutPromises])
@@ -649,13 +810,15 @@ See https://kirujs.dev/docs/api/file-router#404 for more information.`
         path
       )
     } else {
+      const current = scrollStack.get()
+
       // if we've gone back and are now going forward, we need to
       // truncate the scroll stack so it doesn't just permanently grow.
       // this should keep it at the same length as the history stack.
-      const current = scrollStack.get()
       if (this.historyIndex < window.history.length - 1) {
         current.length = this.historyIndex
       }
+
       scrollStack.save([...current, [window.scrollX, window.scrollY]])
       window.history.pushState(
         { ...window.history.state, index: ++this.historyIndex },
@@ -685,23 +848,32 @@ function buildQueryString(
 }
 
 async function handleStateTransition(
-  signal: AbortSignal,
   enableTransition: boolean,
+  id: number,
   callback: () => void
 ) {
+  if (currentTransition) {
+    const { id: currentId, transition } = currentTransition
+    // for cross-page navigations, we skip any existing transitions.
+    // otherwise (eg. loaders), we wait for the existing transition to finish
+    if (id !== currentId) {
+      transition.skipTransition()
+    }
+    await transition.finished
+  }
   if (!enableTransition || typeof document.startViewTransition !== "function") {
     return new Promise<void>((resolve) => {
       callback()
       nextIdle(resolve)
     })
   }
-  const vt = document.startViewTransition(() => {
+  const transition = document.startViewTransition(() => {
     callback()
     flushSync()
   })
-
-  signal.addEventListener("abort", () => vt.skipTransition())
-  await vt.ready
+  currentTransition = { id, transition }
+  await transition.finished
+  currentTransition = null
 }
 
 function validateRoutes(pageMap: FormattedViteImportMap) {

package/src/router/globals.ts

@@ -12,3 +12,7 @@ export const fileRouterRoute = {
 export const routerCache = {
   current: null as RouterCache | null,
 }
+
+export const requestContext = {
+  current: {} as Kiru.RequestContext,
+}