kiru 0.54.0-preview.0 → 0.54.0-preview.1

package/src/router/fileRouterController.ts

@@ -47,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
@@ -92,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() {
@@ -104,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),
@@ -125,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,
@@ -147,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 = {
@@ -158,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
             )
@@ -212,13 +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,
@@ -244,64 +284,46 @@ export class FileRouterController {
       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
-      )
-      this.guards = !guards
-        ? {}
-        : (formatViteImportMap(
-            guards as ViteImportMap,
-            normalizedDir,
-            normalizedBaseUrl
-          ) as unknown as FormattedViteImportMap<GuardModule>)
-
-      if (__DEV__) {
-        validateRoutes(this.pages)
-      }
-      this.loadRoute()
     }
 
     window.history.scrollRestoration = "manual"
@@ -365,15 +387,21 @@ export class FileRouterController {
       }
 
       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 })
     })
   }
 
@@ -422,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
 
@@ -526,7 +556,7 @@ See https://kirujs.dev/docs/api/file-router#404 for more information.`
           path,
           fromPath
         )
-        if (redirectPath) {
+        if (redirectPath !== null) {
           this.state.pathname = path
           return this.navigate(redirectPath, {
             replace: true,
@@ -535,60 +565,58 @@ See https://kirujs.dev/docs/api/file-router#404 for more information.`
         }
       }
 
-      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)
-          }
+      let props: Record<string, unknown> = {}
+      if (!!loader) {
+        props = {
+          data: null,
+          error: null,
+          loading: true,
+        }
+      }
 
-          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,
+      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,
@@ -607,6 +635,16 @@ See https://kirujs.dev/docs/api/file-router#404 for more information.`
             path,
             fromPath
           )
+          if (props.loading) {
+            this.loadRouteData(
+              config as PageConfigWithLoader,
+              routerState,
+              enableTransition,
+              tId
+            ).then(() => signal.aborted || onPaint?.())
+          } else {
+            onPaint?.()
+          }
         })
       })
     } catch (error) {
@@ -617,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
+    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,
@@ -655,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)
+        )
       })
   }
 
@@ -690,20 +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
     }
 
-    if (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"))
       }
@@ -814,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/ssg/index.ts

@@ -86,7 +86,7 @@ export async function render(
   const abortController = new AbortController()
 
   if (config.loader) {
-    if (config.loader.mode !== "static" || __DEV__) {
+    if (!config.loader.static || __DEV__) {
       props = { loading: true, data: null, error: null }
     } else {
       const routerState: RouterState = {

package/src/router/ssr/index.ts

@@ -21,6 +21,8 @@ import type {
   GuardModule,
   PageModule,
 } from "../types.internal.js"
+import { createStatefulPromise } from "../../utils/promise.js"
+import { PAGE_DATA_PROMISE_ID } from "../constants.js"
 
 export interface SSRRenderContext {
   pages: FormattedViteImportMap<PageModule>
@@ -48,14 +50,11 @@ export async function render(
 ): Promise<SSRRenderResult> {
   const extName = path.extname(url)
   if (extName && extName.length > 0) {
-    return {
-      httpResponse: null,
-    }
+    return { httpResponse: null }
   } else if (url.startsWith("/@")) {
-    return {
-      httpResponse: null,
-    }
+    return { httpResponse: null }
   }
+
   const u = new URL(url, "http://localhost")
   const pathSegments = u.pathname.split("/").filter(Boolean)
   let routeMatch = matchRoute(ctx.pages, pathSegments)
@@ -134,35 +133,48 @@ export async function render(
       { ...ctx.userContext },
       u.pathname
     )
-    if (redirectPath) {
+    if (redirectPath !== null) {
       return createRedirectResult(redirectPath)
     }
   }
 
+  let documentShell = renderToString(createElement(ctx.Document))
+
+  if (
+    documentShell.includes("</body>") ||
+    !documentShell.includes("<kiru-body-outlet>")
+  ) {
+    throw new Error(
+      "[kiru/router]: Document is expected to contain a <Body.Outlet> element. See https://kirujs.dev/docs/api/file-router#general-usage"
+    )
+  }
+
   const query = parseQuery(u.search)
 
   let props = {} as PageProps<PageConfig>
   const config = page.config ?? {}
-  const abortController = new AbortController()
+  const abortSignal = new AbortController().signal
+
+  const routerState: RouterState = {
+    params,
+    query,
+    pathname: u.pathname,
+    hash: "",
+    signal: abortSignal,
+  }
 
-  // PageConfig loaders don't run on the server
-  if (config.loader) {
+  let pageDataPromise: Kiru.StatefulPromise<unknown> | null = null
+  if (config.loader && !config.loader.static) {
     props = {
       data: null,
       error: null,
       loading: true,
     }
-  }
-
-  let documentShell = renderToString(createElement(ctx.Document))
-
-  if (
-    documentShell.includes("</body>") ||
-    !documentShell.includes("<kiru-body-outlet>")
-  ) {
-    throw new Error(
-      "[kiru/router]: Document is expected to contain a <Body.Outlet> element. See https://kirujs.dev/docs/api/file-router#general-usage"
-    )
+    const promise = config.loader.load({
+      ...routerState,
+      context: { ...ctx.userContext },
+    })
+    pageDataPromise = createStatefulPromise(PAGE_DATA_PROMISE_ID, promise)
   }
 
   const children = wrapWithLayouts(
@@ -173,25 +185,18 @@ export async function render(
     props
   )
 
-  const routerContextValue = {
-    state: {
-      params,
-      query,
-      pathname: u.pathname,
-      hash: "",
-      signal: abortController.signal,
-    } satisfies RouterState,
-  }
-
   const app = createElement(RouterContext.Provider, {
     children: createElement(RequestContext.Provider, {
       children: Fragment({ children }),
       value: ctx.userContext,
     }),
-    value: routerContextValue,
+    value: { state: routerState },
+  })
+
+  let { immediate: pageOutletContent, stream } = renderToReadableStream(app, {
+    data: pageDataPromise ? [pageDataPromise] : [],
   })
 
-  let { immediate: pageOutletContent, stream } = renderToReadableStream(app)
   const hasHeadContent = pageOutletContent.includes("<kiru-head-content>")
   const hasHeadOutlet = documentShell.includes("<kiru-head-outlet>")
 

package/src/router/types.ts

@@ -13,6 +13,7 @@ export interface FileRouterPreloadConfig {
   guards?: FormattedViteImportMap<GuardModule>
   page: PageModule
   pageProps: Record<string, unknown>
+  pagePropsPromise?: Promise<AsyncTaskState<unknown, FileRouterDataLoadError>>
   pageLayouts: DefaultComponentModule[]
   params: RouteParams
   query: RouteQuery
@@ -139,13 +140,9 @@ export type PageDataLoaderConfig<T = unknown> = {
 } & (
   | {
       /**
-       * The mode to use for the page data loader
-       * @default "client"
-       * @description
-       * - **static**: The page data is loaded at build time and never updated
-       * - **client**: The page data is loaded upon navigation and updated on subsequent navigations
+       * Indicates that the page data should only be loaded at build time
        */
-      mode?: "client"
+      static?: false
       /**
        * Enable transitions when swapping between "load", "error" and "data" states
        */
@@ -165,13 +162,9 @@ export type PageDataLoaderConfig<T = unknown> = {
     }
   | {
       /**
-       * The mode to use for the page data loader
-       * @default "client"
-       * @description
-       * - **static**: The page data is loaded at build time and never updated
-       * - **client**: The page data is loaded upon navigation and updated on subsequent navigations
+       * Indicates that the page data should only be loaded at build time
        */
-      mode: "static"
+      static: true
     }
 )