@vobs/router 1.0.0 → 1.1.0

package/package.json

@@ -6,7 +6,7 @@
     "LICENSE"
   ],
   "name": "@vobs/router",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -14,8 +14,8 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@vobs/reactivity": "1.0.0",
-    "@vobs/runtime": "1.0.0",
-    "@vobs/vobs": "1.0.0"
+    "@vobs/reactivity": "1.1.0",
+    "@vobs/vobs": "1.1.0",
+    "@vobs/runtime": "1.1.0"
   }
 }

package/src/index.test.ts

@@ -40,6 +40,62 @@ describe('@vobs/router', () => {
     router.destroy()
   })
 
+  it('导航 state 随 history 条目存取，back 时恢复', async () => {
+    const router = createRouter({
+      history: createMemoryHistory('/'),
+      routes: [
+        { path: '/', name: 'home', component: () => createText('home') },
+        { path: '/result', name: 'result', component: () => createText('result') }
+      ]
+    })
+
+    // push 携带 state（对象目标与字符串目标的透传路径都要覆盖）
+    await router.push({ path: '/result', state: { orderId: 'A-1' } })
+    expect(router.currentRoute.value.path).toBe('/result')
+    expect(router.currentRoute.value.state).toEqual({ orderId: 'A-1' })
+    expect(router.history.state).toEqual({ orderId: 'A-1' })
+
+    await router.push({ path: '/', state: { orderId: 'A-2' } })
+    expect(router.currentRoute.value.state).toEqual({ orderId: 'A-2' })
+
+    // back 回到上一条目，state 一并恢复
+    router.history.back()
+    await vi.waitFor(() => expect(router.currentRoute.value.path).toBe('/result'))
+    expect(router.currentRoute.value.state).toEqual({ orderId: 'A-1' })
+    router.destroy()
+  })
+
+  it('replace 更新当前条目的 state，同路径 state-only 变更被去重忽略', async () => {
+    const history = createMemoryHistory('/')
+    const router = createRouter({
+      history,
+      routes: [
+        { path: '/', name: 'home', component: () => createText('home') },
+        { path: '/a', name: 'a', component: () => createText('a') },
+        { path: '/b', name: 'b', component: () => createText('b') }
+      ]
+    })
+
+    await router.push('/a')
+    expect(router.currentRoute.value.state).toBeUndefined()
+
+    // replace 到不同路径：state 写入新条目
+    await router.replace({ path: '/b', state: { retried: true } })
+    expect(router.currentRoute.value.path).toBe('/b')
+    expect(router.currentRoute.value.state).toEqual({ retried: true })
+    expect(router.history.state).toEqual({ retried: true })
+
+    // 与既有“相同目标忽略”语义一致：同路径仅 state 变化不会触发导航
+    await router.replace({ path: '/b', state: { retried: false } })
+    expect(router.currentRoute.value.state).toEqual({ retried: true })
+
+    // replace 覆盖了 /a 的条目而非新增：back 直接回到初始 /
+    // （若 replace 误作 push，这里会回到 /a）
+    router.history.back()
+    await vi.waitFor(() => expect(router.currentRoute.value.path).toBe('/'))
+    router.destroy()
+  })
+
   it('支持无路径父路由、嵌套 children、父子 meta 合并和命名导航', () => {
     const Layout = () => createText('layout')
     const router = createRouter({

package/src/index.ts

@@ -37,6 +37,7 @@ export interface RouteLocation {
   readonly meta: RouteMeta
   readonly record: RouteRecord | null
   readonly matched: readonly RouteRecord[]
+  readonly state?: unknown
 }
 
 export interface RouteComponentProps {
@@ -84,6 +85,7 @@ export interface RouteLocationRaw {
   readonly params?: Record<string, unknown>
   readonly query?: RouteQueryInput
   readonly hash?: string
+  readonly state?: unknown
 }
 
 export type RouteTarget = string | RouteLocationRaw
@@ -114,10 +116,12 @@ export class NavigationRedirectError extends Error {
 
 export interface RouterHistory {
   readonly location: string
-  push(path: string): void
-  replace(path: string): void
+  /** 当前 history 条目携带的导航 state（push/replace 时写入，popstate/初始启动时回读）。 */
+  readonly state?: unknown
+  push(path: string, state?: unknown): void
+  replace(path: string, state?: unknown): void
   back(): void
-  listen(listener: (path: string) => void): () => void
+  listen(listener: (path: string, state: unknown) => void): () => void
 }
 
 export interface RouterOptions {
@@ -269,33 +273,37 @@ export function lazy(loader: RouteComponentLoader): LazyRouteComponent {
 }
 
 export function createMemoryHistory(initial = '/'): RouterHistory {
-  let entries = [normalizeHistoryPath(initial)]
+  let entries = [{ path: normalizeHistoryPath(initial), state: undefined as unknown }]
   let index = 0
-  const listeners = new Set<(path: string) => void>()
+  const listeners = new Set<(path: string, state: unknown) => void>()
 
   return {
     get location(): string {
-      return entries[index]
+      return entries[index]!.path
     },
 
-    push(path: string): void {
+    get state(): unknown {
+      return entries[index]!.state
+    },
+
+    push(path: string, state?: unknown): void {
       const next = normalizeHistoryPath(path)
       entries = entries.slice(0, index + 1)
-      entries.push(next)
+      entries.push({ path: next, state })
       index++
     },
 
-    replace(path: string): void {
-      entries[index] = normalizeHistoryPath(path)
+    replace(path: string, state?: unknown): void {
+      entries[index] = { path: normalizeHistoryPath(path), state }
     },
 
     back(): void {
       if (index === 0) return
       index--
-      notifyListeners(listeners, entries[index])
+      notifyListeners(listeners, entries[index]!.path, entries[index]!.state)
     },
 
-    listen(listener: (path: string) => void): () => void {
+    listen(listener: (path: string, state: unknown) => void): () => void {
       listeners.add(listener)
       return () => listeners.delete(listener)
     }
@@ -308,9 +316,9 @@ export function createBrowserHistory(base = ''): RouterHistory {
   }
 
   const normalizedBase = normalizeBase(base)
-  const listeners = new Set<(path: string) => void>()
-  const onPopState = (): void => {
-    notifyListeners(listeners, readBrowserLocation(normalizedBase))
+  const listeners = new Set<(path: string, state: unknown) => void>()
+  const onPopState = (event: PopStateEvent): void => {
+    notifyListeners(listeners, readBrowserLocation(normalizedBase), event.state)
   }
 
   return {
@@ -318,19 +326,23 @@ export function createBrowserHistory(base = ''): RouterHistory {
       return readBrowserLocation(normalizedBase)
     },
 
-    push(path: string): void {
-      window.history.pushState(null, '', withBase(normalizeHistoryPath(path), normalizedBase))
+    get state(): unknown {
+      return window.history.state
+    },
+
+    push(path: string, state?: unknown): void {
+      window.history.pushState(state ?? null, '', withBase(normalizeHistoryPath(path), normalizedBase))
     },
 
-    replace(path: string): void {
-      window.history.replaceState(null, '', withBase(normalizeHistoryPath(path), normalizedBase))
+    replace(path: string, state?: unknown): void {
+      window.history.replaceState(state ?? null, '', withBase(normalizeHistoryPath(path), normalizedBase))
     },
 
     back(): void {
       window.history.back()
     },
 
-    listen(listener: (path: string) => void): () => void {
+    listen(listener: (path: string, state: unknown) => void): () => void {
       if (listeners.size === 0) window.addEventListener('popstate', onPopState)
       listeners.add(listener)
       return () => {
@@ -368,10 +380,10 @@ export function createRouter(options: RouterOptions): Router {
   function resolve(to: RouteTarget): RouteLocation {
     ensureActive()
     const target = typeof to === 'string' ? parseTargetString(to) : normalizeTarget(to, matchers)
-    return resolvePath(buildTargetPath(target.path, target.query, target.hash))
+    return resolvePath(buildTargetPath(target.path, target.query, target.hash), target.state)
   }
 
-  function resolvePath(rawPath: string): RouteLocation {
+  function resolvePath(rawPath: string, state?: unknown): RouteLocation {
     const parsed = parseTargetString(rawPath)
     const matched = matchers.find(matcher => matcher.regex.exec(parsed.path))
     const params = matched ? extractParams(matched, parsed.path) : {}
@@ -387,19 +399,23 @@ export function createRouter(options: RouterOptions): Router {
       name: record?.name,
       meta: matched?.meta ?? {},
       record,
-      matched: matched?.chain ?? EMPTY_MATCHED
+      matched: matched?.chain ?? EMPTY_MATCHED,
+      state
     }
   }
 
   async function navigate(
     to: RouteTarget,
     replaceHistory: boolean,
-    fromHistory: boolean
+    fromHistory: boolean,
+    historyState?: unknown
   ): Promise<RouteLocation | false> {
     ensureActive()
     const id = ++navigationId
     const from = currentRoute.value
     let target = resolve(to)
+    // popstate 回读的 state 保存在 history 条目上，不在目标描述里，这里回填。
+    if (fromHistory && historyState !== undefined) target = { ...target, state: historyState }
     const source: NavigationTrace['source'] = fromHistory ? 'history' : replaceHistory ? 'replace' : 'push'
     const startedAt = now()
     const initialTarget = target.fullPath
@@ -470,8 +486,8 @@ export function createRouter(options: RouterOptions): Router {
 
         if (target.fullPath === from.fullPath) return from
         if (!fromHistory) {
-          if (replaceHistory) history.replace(target.fullPath)
-          else history.push(target.fullPath)
+          if (replaceHistory) history.replace(target.fullPath, target.state)
+          else history.push(target.fullPath, target.state)
         }
         currentRoute.value = target
         recordNavigation({ id, from: from.fullPath, to: target.fullPath, status: 'success', source, startedAt, endedAt: now(), duration: now() - startedAt, redirect: target.fullPath !== initialTarget ? target.fullPath : undefined })
@@ -615,13 +631,13 @@ export function createRouter(options: RouterOptions): Router {
     return buildRouteDebugTree(options.routes, statuses)
   }
 
-  function handleHistoryNavigation(path: string): void {
-    void navigate(path, false, true).then(result => {
+  function handleHistoryNavigation(path: string, state: unknown): void {
+    void navigate(path, false, true, state).then(result => {
       if (destroyed) return
       if (result === false) {
-        history.replace(currentRoute.value.fullPath)
+        history.replace(currentRoute.value.fullPath, currentRoute.value.state)
       } else if (result.fullPath !== normalizeHistoryPath(path)) {
-        history.replace(result.fullPath)
+        history.replace(result.fullPath, result.state)
       }
     }).catch(error => {
       if (!(error instanceof NavigationCancelledError) && !destroyed) {
@@ -630,7 +646,7 @@ export function createRouter(options: RouterOptions): Router {
         reportError('navigation', failed, normalizeHistoryPath(path))
         navigationState = { status: 'error', from: current, to: normalizeHistoryPath(path), error: failed.message }
         emitRouter('navigation:end', { status: 'error', from: current, to: normalizeHistoryPath(path), error: failed.message })
-        history.replace(currentRoute.value.fullPath)
+        history.replace(currentRoute.value.fullPath, currentRoute.value.state)
       }
     })
   }
@@ -872,6 +888,7 @@ interface ParsedTarget {
   readonly path: string
   readonly query: RouteQuery
   readonly hash: string
+  readonly state?: unknown
 }
 
 function defaultHistory(): RouterHistory {
@@ -1024,7 +1041,7 @@ function normalizeTarget(target: RouteLocationRaw, matchers: readonly RouteMatch
   const filledPath = fillRouteParams(parsed.path, target.params ?? {})
   const query = target.query === undefined ? parsed.query : normalizeQuery(target.query)
   const hash = target.hash === undefined ? parsed.hash : normalizeHash(target.hash)
-  return { path: filledPath, query, hash }
+  return { path: filledPath, query, hash, state: target.state }
 }
 
 function fillRouteParams(path: string, params: Record<string, unknown>): string {
@@ -1110,8 +1127,8 @@ function withBase(path: string, base: string): string {
   return `${base}${path === '/' ? '/' : path}` || '/'
 }
 
-function notifyListeners(listeners: Set<(path: string) => void>, path: string): void {
-  for (const listener of [...listeners]) listener(path)
+function notifyListeners(listeners: Set<(path: string, state: unknown) => void>, path: string, state: unknown): void {
+  for (const listener of [...listeners]) listener(path, state)
 }
 
 function escapeRegExp(value: string): string {