@fictjs/router 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fictjs/router",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Reactive router for Fict applications",
   "publishConfig": {
     "access": "public",
@@ -13,8 +13,6 @@
     "spa",
     "reactive"
   ],
-  "author": "Michael Lin",
-  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/fictjs/fict.git",
@@ -37,22 +35,25 @@
     "src"
   ],
   "dependencies": {
-    "@fictjs/runtime": "0.3.0"
+    "@fictjs/runtime": "0.5.0"
   },
   "devDependencies": {
     "jsdom": "^27.4.0",
     "tsup": "^8.5.1",
-    "@fictjs/vite-plugin": "0.3.0",
-    "fict": "0.3.0"
+    "@fictjs/testing-library": "0.5.0",
+    "@fictjs/vite-plugin": "0.5.0",
+    "fict": "0.5.0"
   },
   "peerDependencies": {
-    "fict": "0.3.0"
+    "fict": ">=0.3.0"
   },
   "peerDependenciesMeta": {
     "fict": {
       "optional": true
     }
   },
+  "author": "unadlib",
+  "license": "MIT",
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",

package/src/accessor-utils.ts

@@ -0,0 +1,22 @@
+export function wrapAccessor<T extends (...args: any[]) => any>(fn: T): T {
+  const wrapped = ((...args: any[]) => {
+    if (args.length === 0) return wrapped
+    return fn(...(args as Parameters<T>))
+  }) as unknown as T
+  return wrapped
+}
+
+export function wrapValue<T>(value: T): T {
+  const wrapped = (() => value) as unknown as T & {
+    toString?: () => string
+    valueOf?: () => T
+  }
+
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    const primitive = value
+    wrapped.toString = () => String(primitive)
+    wrapped.valueOf = () => primitive
+  }
+
+  return wrapped as unknown as T
+}

package/src/components.tsx

@@ -7,11 +7,7 @@
 
 import {
   createEffect,
-  onCleanup,
   createMemo,
-  batch,
-  untrack,
-  startTransition,
   Fragment,
   Suspense,
   ErrorBoundary,
@@ -20,51 +16,28 @@ import {
 } from '@fictjs/runtime'
 import { createSignal } from '@fictjs/runtime/advanced'
 
-import {
-  RouterContext,
-  RouteContext,
-  BeforeLeaveContext,
-  RouteErrorContext,
-  useRouter,
-  useRoute,
-  type BeforeLeaveContextValue,
-} from './context'
+import { wrapAccessor } from './accessor-utils'
+import { RouteContext, RouteErrorContext, useRouter, useRoute, readAccessor } from './context'
 import {
   createBrowserHistory,
   createHashHistory,
   createMemoryHistory,
   createStaticHistory,
 } from './history'
+import { stripBaseOrWarn } from './router-internals'
+import { RouterProvider } from './router-provider'
 import type {
-  History,
-  Location,
   RouteDefinition,
+  Location,
   RouteMatch,
-  RouterContextValue,
   RouteContextValue,
-  NavigateFunction,
-  NavigateOptions,
   To,
   Params,
-  BeforeLeaveHandler,
-  BeforeLeaveEventArgs,
   MemoryRouterOptions,
   HashRouterOptions,
   RouterOptions,
 } from './types'
-import {
-  compileRoute,
-  createBranches,
-  matchRoutes,
-  resolvePath,
-  createLocation,
-  normalizePath,
-  isBrowser,
-  stripBasePath,
-  prependBasePath,
-  locationsAreEqual,
-} from './utils'
-import { getScrollRestoration } from './scroll'
+import { compileRoute, createBranches, matchRoutes, resolvePath } from './utils'
 
 // Use Fict's signal for reactive state
 
@@ -72,317 +45,10 @@ import { getScrollRestoration } from './scroll'
 // Internal State Types
 // ============================================================================
 
-interface RouterState {
-  location: Location
-  matches: RouteMatch[]
-  isRouting: boolean
-  pendingLocation: Location | null
-}
-
-const isDevEnv =
-  (typeof import.meta !== 'undefined' &&
-    (import.meta as { env?: { DEV?: boolean } }).env?.DEV === true) ||
-  (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production')
-
-let didWarnBaseMismatch = false
-
-function hasBasePrefix(pathname: string, base: string): boolean {
-  if (!base) return true
-  return pathname === base || pathname.startsWith(base + '/')
-}
-
-function stripBaseOrWarn(pathname: string, base: string): string | null {
-  if (!base) return pathname
-  if (!hasBasePrefix(pathname, base)) {
-    if (isDevEnv && !didWarnBaseMismatch) {
-      didWarnBaseMismatch = true
-      console.warn(
-        `[fict-router] Location "${pathname}" does not start with base "${base}". No routes matched.`,
-      )
-    }
-    return null
-  }
-  return stripBasePath(pathname, base)
-}
-
-function stripBaseIfPresent(pathname: string, base: string): string {
-  if (!base) return pathname
-  if (hasBasePrefix(pathname, base)) {
-    return stripBasePath(pathname, base)
-  }
-  return pathname
-}
-
-// ============================================================================
-// createRouter - Core router factory
-// ============================================================================
-
-/**
- * Create a router instance with the given history and routes
- */
-function createRouterState(
-  history: History,
-  routes: RouteDefinition[],
-  base = '',
-): {
-  state: () => RouterState
-  navigate: NavigateFunction
-  beforeLeave: BeforeLeaveContextValue
-  cleanup: () => void
-  normalizedBase: string
-} {
-  // Normalize the base path
-  const normalizedBase = normalizePath(base)
-  const baseForStrip = normalizedBase === '/' ? '' : normalizedBase
-
-  // Compile routes into branches for efficient matching
-  const compiledRoutes = routes.map(r => compileRoute(r))
-  const branches = createBranches(compiledRoutes)
-
-  // Helper to match with base path stripped
-  const matchWithBase = (pathname: string): RouteMatch[] => {
-    const strippedPath = stripBaseOrWarn(pathname, baseForStrip)
-    if (strippedPath == null) return []
-    return matchRoutes(branches, strippedPath) || []
-  }
-
-  // Initial state
-  const initialLocation = history.location
-  const initialMatches = matchWithBase(initialLocation.pathname)
-
-  // Reactive state using signals
-  const locationSignal = createSignal<Location>(initialLocation)
-  const matchesSignal = createSignal<RouteMatch[]>(initialMatches)
-  const isRoutingSignal = createSignal<boolean>(false)
-  const pendingLocationSignal = createSignal<Location | null>(null)
-
-  // BeforeLeave handlers and navigation token for async ordering
-  const beforeLeaveHandlers = new Set<BeforeLeaveHandler>()
-  let navigationToken = 0
-
-  const beforeLeave: BeforeLeaveContextValue = {
-    addHandler(handler: BeforeLeaveHandler) {
-      beforeLeaveHandlers.add(handler)
-      return () => beforeLeaveHandlers.delete(handler)
-    },
-    async confirm(to: Location, from: Location): Promise<boolean> {
-      if (beforeLeaveHandlers.size === 0) return true
-
-      // Capture current token for this navigation
-      const currentToken = ++navigationToken
-
-      let defaultPrevented = false
-      let retryRequested = false
-      let forceRetry = false
-
-      const event: BeforeLeaveEventArgs = {
-        to,
-        from,
-        get defaultPrevented() {
-          return defaultPrevented
-        },
-        preventDefault() {
-          defaultPrevented = true
-        },
-        retry(force?: boolean) {
-          retryRequested = true
-          forceRetry = force ?? false
-        },
-      }
-
-      for (const handler of beforeLeaveHandlers) {
-        await handler(event)
-
-        // Check if this navigation is still current (not superseded by newer navigation)
-        if (currentToken !== navigationToken) {
-          // This navigation was superseded, ignore its result
-          return false
-        }
-
-        if (defaultPrevented && !retryRequested) {
-          return false
-        }
-        if (retryRequested && forceRetry) {
-          return true
-        }
-      }
-
-      // Final check that this navigation is still current
-      if (currentToken !== navigationToken) {
-        return false
-      }
-
-      return !defaultPrevented || retryRequested
-    },
-  }
-
-  // Navigation function
-  const navigate: NavigateFunction = (toOrDelta: To | number, options?: NavigateOptions) => {
-    if (typeof toOrDelta === 'number') {
-      history.go(toOrDelta)
-      return
-    }
-
-    const currentLocation = locationSignal()
-    const to = toOrDelta
-
-    // Extract pathname, search, and hash from string without normalizing pathname
-    // This preserves relative paths like 'settings' vs '/settings'
-    let toPathname: string
-    let toSearch = ''
-    let toHash = ''
-
-    if (typeof to === 'string') {
-      // Extract hash first
-      let remaining = to
-      const hashIndex = remaining.indexOf('#')
-      if (hashIndex >= 0) {
-        toHash = remaining.slice(hashIndex)
-        remaining = remaining.slice(0, hashIndex)
-      }
-      // Extract search
-      const searchIndex = remaining.indexOf('?')
-      if (searchIndex >= 0) {
-        toSearch = remaining.slice(searchIndex)
-        remaining = remaining.slice(0, searchIndex)
-      }
-      // Remaining is the pathname (keep empty string for search/hash-only navigation)
-      toPathname = remaining
-    } else {
-      toPathname = to.pathname || ''
-      toSearch = to.search || ''
-      toHash = to.hash || ''
-    }
-
-    // Resolve the target path (relative to current path, without base)
-    let targetPath: string
-    const currentPathWithoutBase = stripBaseOrWarn(currentLocation.pathname, baseForStrip) || '/'
-
-    if (typeof to === 'string') {
-      // Empty pathname means search/hash-only navigation - keep current path
-      if (toPathname === '') {
-        targetPath = currentPathWithoutBase
-      } else if (options?.relative === 'route') {
-        // Resolve relative to current route
-        const matches = matchesSignal()
-        const currentMatch = matches[matches.length - 1]
-        const currentRoutePath = currentMatch?.pathname || currentPathWithoutBase
-        targetPath = resolvePath(currentRoutePath, toPathname)
-      } else {
-        // Resolve relative to current pathname
-        // Only strip base if it's an absolute path
-        targetPath = toPathname.startsWith('/')
-          ? stripBaseIfPresent(toPathname, baseForStrip)
-          : resolvePath(currentPathWithoutBase, toPathname)
-      }
-    } else {
-      const rawTargetPath = toPathname || currentPathWithoutBase
-      targetPath = stripBaseIfPresent(rawTargetPath, baseForStrip)
-    }
-
-    // Create the full target location, preserving to.state and to.key
-    // options.state overrides to.state if provided
-    const toState = typeof to === 'object' ? to.state : undefined
-    const toKey = typeof to === 'object' ? to.key : undefined
-    const finalState = options?.state !== undefined ? options.state : toState
-
-    // Build location object, only including key if defined
-    const targetPathWithBase = prependBasePath(targetPath, baseForStrip)
-    const locationSpec: Partial<Location> = {
-      pathname: targetPathWithBase,
-      search: toSearch,
-      hash: toHash,
-    }
-    if (finalState !== undefined) {
-      locationSpec.state = finalState
-    }
-    if (toKey !== undefined) {
-      locationSpec.key = toKey
-    }
-
-    const targetLocation = createLocation(locationSpec, finalState, toKey)
-
-    // Check beforeLeave handlers
-    untrack(async () => {
-      const canNavigate = await beforeLeave.confirm(targetLocation, currentLocation)
-      if (!canNavigate) {
-        pendingLocationSignal(null)
-        return
-      }
-
-      // Start routing indicator and set pending location
-      batch(() => {
-        isRoutingSignal(true)
-        pendingLocationSignal(targetLocation)
-      })
-
-      // Use transition for smooth updates
-      // Note: We only push/replace to history here.
-      // The actual signal updates happen in history.listen to avoid duplicates.
-      startTransition(() => {
-        const prevLocation = history.location
-        if (options?.replace) {
-          history.replace(targetLocation, finalState)
-        } else {
-          history.push(targetLocation, finalState)
-        }
-
-        // Scroll handling for programmatic navigation
-        if (options?.scroll !== false && isBrowser()) {
-          const scrollRestoration = getScrollRestoration()
-          scrollRestoration.handleNavigation(
-            prevLocation,
-            history.location,
-            options?.replace ? 'REPLACE' : 'PUSH',
-          )
-        }
-
-        // If navigation was blocked or no-op, reset routing state
-        if (locationsAreEqual(prevLocation, history.location)) {
-          batch(() => {
-            isRoutingSignal(false)
-            pendingLocationSignal(null)
-          })
-        }
-      })
-    })
-  }
-
-  // Listen for history changes (browser back/forward AND navigate calls)
-  // This is the single source of truth for location/matches updates
-  const unlisten = history.listen(({ action, location: newLocation }) => {
-    const prevLocation = locationSignal()
-
-    batch(() => {
-      locationSignal(newLocation)
-      const newMatches = matchWithBase(newLocation.pathname)
-      matchesSignal(newMatches)
-      isRoutingSignal(false)
-      pendingLocationSignal(null)
-    })
-
-    // Handle scroll restoration for POP navigation (back/forward)
-    if (action === 'POP' && isBrowser()) {
-      const scrollRestoration = getScrollRestoration()
-      scrollRestoration.handleNavigation(prevLocation, newLocation, 'POP')
-    }
-  })
-
-  // State accessor
-  const state = () => ({
-    location: locationSignal(),
-    matches: matchesSignal(),
-    isRouting: isRoutingSignal(),
-    pendingLocation: pendingLocationSignal(),
-  })
-
-  return {
-    state,
-    navigate,
-    beforeLeave,
-    cleanup: unlisten,
-    normalizedBase: baseForStrip,
-  }
+interface RouteDataState<T = unknown> {
+  data: T | undefined
+  error: unknown
+  loading: boolean
 }
 
 // ============================================================================
@@ -401,60 +67,6 @@ interface StaticRouterProps extends BaseRouterProps {
   url: string
 }
 
-/**
- * Internal router component that sets up the context
- */
-function RouterProvider(props: {
-  history: History
-  routes: RouteDefinition[]
-  base?: string | undefined
-  children?: FictNode
-}) {
-  const { state, navigate, beforeLeave, cleanup, normalizedBase } = createRouterState(
-    props.history,
-    props.routes,
-    props.base,
-  )
-
-  onCleanup(cleanup)
-
-  const routerContext: RouterContextValue = {
-    location: () => state().location,
-    params: () => {
-      const matches = state().matches
-      // Use Record<string, string | undefined> for type precision
-      const allParams: Record<string, string | undefined> = {}
-      for (const match of matches) {
-        Object.assign(allParams, match.params)
-      }
-      return allParams as Params
-    },
-    matches: () => state().matches,
-    navigate,
-    isRouting: () => state().isRouting,
-    pendingLocation: () => state().pendingLocation,
-    base: normalizedBase,
-    resolvePath: (to: To) => {
-      // Resolve path relative to current location (without base)
-      const location = state().location
-      const currentPathWithoutBase = stripBaseOrWarn(location.pathname, normalizedBase) || '/'
-      const rawTargetPath = typeof to === 'string' ? to : to.pathname || '/'
-      const targetPath = rawTargetPath.startsWith('/')
-        ? stripBaseIfPresent(rawTargetPath, normalizedBase)
-        : rawTargetPath
-      return resolvePath(currentPathWithoutBase, targetPath)
-    },
-  }
-
-  return (
-    <RouterContext.Provider value={routerContext}>
-      <BeforeLeaveContext.Provider value={beforeLeave}>
-        {props.children}
-      </BeforeLeaveContext.Provider>
-    </RouterContext.Provider>
-  )
-}
-
 /**
  * Browser Router - uses the History API
  */
@@ -545,9 +157,11 @@ export function Routes(props: RoutesProps) {
 
   // Create reactive memo for current matches
   const currentMatches = createMemo(() => {
-    const location = router.location()
-    const parentMatch = parentRoute.match()
-    const locationPath = stripBaseOrWarn(location.pathname, router.base)
+    const pendingLocation = readAccessor(router.pendingLocation)
+    const location = pendingLocation ?? readAccessor(router.location)
+    const parentMatch = readAccessor(parentRoute.match)
+    const base = readAccessor(router.base)
+    const locationPath = stripBaseOrWarn(location.pathname, base)
     if (locationPath == null) return []
 
     // Calculate the remaining path after parent route
@@ -565,26 +179,15 @@ export function Routes(props: RoutesProps) {
   })
 
   // Render the matched routes
-  return <>{renderMatches(currentMatches(), 0)}</>
+  const matches = currentMatches()
+  return <>{matches.length > 0 ? renderMatches(matches, 0) : null}</>
 }
 
-/**
- * Route data state for preloading
- */
-interface RouteDataState<T = unknown> {
-  data: T | undefined
-  error: unknown
-  loading: boolean
-}
-
-/**
- * Render route matches recursively with data loading support
- */
-function renderMatches(matches: RouteMatch[], index: number): FictNode {
-  if (index >= matches.length) {
-    return null
-  }
+// ============================================================================
+// Route Component
+// ============================================================================
 
+export function renderMatches(matches: RouteMatch[], index: number): FictNode {
   const match = matches[index]!
   const route = match.route
   const router = useRouter()
@@ -603,7 +206,7 @@ function renderMatches(matches: RouteMatch[], index: number): FictNode {
   if (route.preload) {
     // Trigger preload on initial render and when location changes
     createEffect(() => {
-      const location = router.location()
+      const location = readAccessor(router.location)
       const preloadArgs = {
         params: match.params,
         location,
@@ -631,18 +234,7 @@ function renderMatches(matches: RouteMatch[], index: number): FictNode {
     })
   }
 
-  // Create route context for this level
-  const routeContext: RouteContextValue = {
-    match: () => match,
-    data: () => dataState().data,
-    error: () => dataState().error,
-    outlet: () => renderMatches(matches, index + 1),
-    resolvePath: (to: To) => {
-      const basePath = match.pathname
-      const targetPath = typeof to === 'string' ? to : to.pathname || '/'
-      return resolvePath(basePath, targetPath)
-    },
-  }
+  const outletNode = <Outlet />
 
   // Determine what to render
   const renderContent = (): FictNode => {
@@ -660,30 +252,48 @@ function renderMatches(matches: RouteMatch[], index: number): FictNode {
 
     // Render the normal content
     if (route.component) {
-      const Component = route.component
+      const Component = route.component as Component<{
+        params: Params
+        location: Location
+        data: unknown
+        children?: FictNode
+      }>
       return (
-        <Component params={match.params} location={router.location()} data={state.data}>
-          <Outlet />
+        <Component params={match.params} location={readAccessor(router.location)} data={state.data}>
+          {outletNode}
         </Component>
       )
-    } else if (route.element) {
+    }
+    if (route.element) {
       return route.element
-    } else if (route.children) {
+    }
+    if (route.children) {
       // Layout route without component - just render outlet
-      return <Outlet />
+      return outletNode
     }
 
     return null
   }
 
+  // Create route context for this level
+  const routeContext: RouteContextValue = {
+    match: () => match,
+    data: () => dataState().data,
+    error: () => dataState().error,
+    outlet: () => (index + 1 < matches.length ? renderMatches(matches, index + 1) : null),
+    resolvePath: wrapAccessor((to: To) => {
+      const basePath = match.pathname
+      const targetPath = typeof to === 'string' ? to : to.pathname || '/'
+      return resolvePath(basePath, targetPath)
+    }),
+  }
+
   // Build the route content with context provider
   let content: FictNode = (
     <RouteContext.Provider value={routeContext}>{renderContent()}</RouteContext.Provider>
   )
 
   // Always wrap with ErrorBoundary if errorElement is defined
-  // This catches both preload errors (handled in renderContent) AND render errors from components
-  // Use a function fallback to pass the error via RouteErrorContext for useRouteError()
   if (route.errorElement) {
     content = (
       <ErrorBoundary
@@ -706,10 +316,6 @@ function renderMatches(matches: RouteMatch[], index: number): FictNode {
   return content
 }
 
-// ============================================================================
-// Route Component
-// ============================================================================
-
 interface RouteJSXProps {
   path?: string | undefined
   component?: Component<any> | undefined
@@ -738,16 +344,9 @@ export function Route(_props: RouteJSXProps): FictNode {
   return null
 }
 
-// ============================================================================
-// Outlet Component
-// ============================================================================
-
-/**
- * Outlet component - renders the child route
- */
 export function Outlet(): FictNode {
   const route = useRoute()
-  return <>{route.outlet()}</>
+  return readAccessor(route.outlet)
 }
 
 // ============================================================================