vue-stack-tabs 1.0.1 → 1.3.0

package/src/lib/hooks/tabPanel/navigationTransaction.ts

@@ -0,0 +1,61 @@
+/**
+ * 导航事务管理器。
+ *
+ * 将「乐观 UI 更新 → 路由导航 → 确认/回滚」包装为原子事务：
+ * 1. apply()  — 先对 UI 状态做乐观修改，返回快照
+ * 2. navigate() — 执行 router.push 等异步导航
+ * 3. 成功 → commit()；失败/异常 → rollback(snapshot) 恢复快照
+ *
+ * 当连续快速操作导致事务过期时（isCurrent 返回 false），
+ * 不回滚而是调用 cleanupStale() 清理残留状态，避免覆盖新事务的结果。
+ */
+interface NavigationTransactionOptions<TSnapshot, TResult> {
+  /** 乐观应用 UI 变更，返回可用于 rollback 的快照 */
+  apply: () => TSnapshot
+  /** 执行异步路由导航 */
+  navigate: () => Promise<TResult>
+  /** 导航失败时回滚到快照状态 */
+  rollback: (snapshot: TSnapshot) => void
+  /** 导航成功后的确认回调（如驱逐旧缓存） */
+  commit?: () => void
+  /** 判断导航结果是否为失败（如 vue-router 返回的 NavigationFailure） */
+  isFailureResult?: (result: TResult) => boolean
+  /** 若为失败结果，是否将其作为异常抛出 */
+  rejectFailureResult?: boolean
+  /** 检查当前事务是否仍然有效（防止过期事务覆盖新状态） */
+  isCurrent?: () => boolean
+  /** 事务已过期时的清理回调（替代 rollback） */
+  cleanupStale?: () => void
+}
+
+/**
+ * 执行一次导航事务：apply → navigate → commit/rollback。
+ * 保证乐观更新在导航失败时能安全回滚。
+ */
+export const runNavigationTransaction = async <TSnapshot, TResult>(
+  options: NavigationTransactionOptions<TSnapshot, TResult>
+): Promise<TResult> => {
+  const snapshot = options.apply()
+
+  try {
+    const result = await options.navigate()
+    if (options.isFailureResult?.(result)) {
+      if (options.isCurrent?.() ?? true) {
+        options.rollback(snapshot)
+      } else {
+        options.cleanupStale?.()
+      }
+      if (options.rejectFailureResult) throw result
+      return result
+    }
+    if (options.isCurrent?.() ?? true) options.commit?.()
+    return result
+  } catch (error) {
+    if (options.isCurrent?.() ?? true) {
+      options.rollback(snapshot)
+    } else {
+      options.cleanupStale?.()
+    }
+    throw error
+  }
+}

package/src/lib/hooks/tabPanel/refresh.ts

@@ -0,0 +1,109 @@
+/**
+ * tabPanel/refresh - 普通页面与 iframe 标签的刷新逻辑。
+ *
+ * 活动普通页面保持 cache id 稳定，只递增页面级刷新版本；非活动页面可直接替换缓存。
+ */
+import type { Ref } from 'vue'
+import type { ITabItem } from '../../model/TabModel'
+
+export interface TabPanelRefreshApi {
+  refreshTab: (id: string) => void
+  refreshAllTabs: () => void
+}
+
+export interface CreateTabPanelRefreshOptions {
+  tabs: Ref<ITabItem[]>
+  iframeRefreshKeys: Ref<Record<string, number>>
+  getTab: (id: string) => ITabItem | null
+  createPageId: () => string
+  addCache: (cacheName: string) => void
+  evictPageCache: (cacheName: string) => void
+  replacePageCaches: (
+    cacheNamesToEvict: Iterable<string>,
+    cacheNamesToAdd: Iterable<string>
+  ) => void
+  refreshIframeByPostMessage: (tabId: string) => void
+}
+
+export const createTabPanelRefresh = (
+  options: CreateTabPanelRefreshOptions
+): TabPanelRefreshApi => {
+  const {
+    tabs,
+    iframeRefreshKeys,
+    getTab,
+    createPageId,
+    addCache,
+    evictPageCache,
+    replacePageCaches,
+    refreshIframeByPostMessage
+  } = options
+
+  const refreshIframe = (tab: ITabItem) => {
+    if (tab.iframeRefreshMode === 'reload') {
+      iframeRefreshKeys.value = {
+        ...iframeRefreshKeys.value,
+        [tab.id]: (iframeRefreshKeys.value[tab.id] ?? 0) + 1
+      }
+      return
+    }
+    refreshIframeByPostMessage(tab.id)
+  }
+
+  const refreshPage = (tab: ITabItem, cacheNamesToEvict?: string[], cacheNamesToAdd?: string[]) => {
+    const currentPage = tab.pages.peek()
+    if (!currentPage) return
+
+    if (tab.active) {
+      currentPage.refreshVersion = (currentPage.refreshVersion ?? 0) + 1
+      return
+    }
+
+    const oldCacheName = currentPage.id
+    currentPage.id = createPageId()
+    currentPage.refreshVersion = 0
+    if (cacheNamesToEvict && cacheNamesToAdd) {
+      cacheNamesToEvict.push(oldCacheName)
+      cacheNamesToAdd.push(currentPage.id)
+      return
+    }
+    evictPageCache(oldCacheName)
+    addCache(currentPage.id)
+  }
+
+  const refreshTab = (id: string) => {
+    const tab = getTab(id)
+    if (!tab?.refreshable) return
+    if (tab.iframe) {
+      refreshIframe(tab)
+      return
+    }
+    refreshPage(tab)
+  }
+
+  const refreshAllTabs = () => {
+    const cacheNamesToEvict: string[] = []
+    const cacheNamesToAdd: string[] = []
+    const iframeKeysUpdate = { ...iframeRefreshKeys.value }
+    let iframeKeysChanged = false
+
+    for (const tab of tabs.value) {
+      if (!tab.refreshable) continue
+      if (tab.iframe) {
+        if (tab.iframeRefreshMode === 'reload') {
+          iframeKeysUpdate[tab.id] = (iframeKeysUpdate[tab.id] ?? 0) + 1
+          iframeKeysChanged = true
+        } else {
+          refreshIframeByPostMessage(tab.id)
+        }
+        continue
+      }
+      refreshPage(tab, cacheNamesToEvict, cacheNamesToAdd)
+    }
+
+    if (iframeKeysChanged) iframeRefreshKeys.value = iframeKeysUpdate
+    replacePageCaches(cacheNamesToEvict, cacheNamesToAdd)
+  }
+
+  return { refreshTab, refreshAllTabs }
+}

package/src/lib/hooks/tabPanel/scroll.ts

@@ -1,52 +1,73 @@
 /**
  * tabPanel/scroll - 滚动位置保存与恢复
  *
- * 职责：在切出/切入页面时保存和恢复滚动位置
+ * 职责：基于当前 StackTabsRuntimeContext 在切出/切入页面时保存和恢复滚动位置。
  */
-import { scrollPositionsByPageId } from './state'
-
-/** 恢复指定页面的滚动位置 */
-export const restoreScroller = (pageCacheId: string) => {
-  const positions = scrollPositionsByPageId.get(pageCacheId)
-  if (!positions) return
-  for (const [sel, pos] of positions) {
-    const el = document.querySelector(sel) as HTMLElement | null
-    if (el) {
-      el.scrollTop = pos.top
-      el.scrollLeft = pos.left
+import type { StackTabsRuntimeContext } from '../stackTabsContext'
+
+export interface TabPanelScrollApi {
+  restoreScroller: (pageCacheId: string) => void
+  saveScroller: (pageCacheId: string) => void
+  removeScroller: (pageCacheId: string) => void
+  addPageScroller: (pageCacheId: string, ...selectorIds: string[]) => void
+}
+
+const resolveScrollElement = (selector: string): HTMLElement | null =>
+  selector.startsWith('#')
+    ? document.getElementById(selector.slice(1))
+    : (document.querySelector(selector) as HTMLElement | null)
+
+export const createTabPanelScroll = (context: StackTabsRuntimeContext): TabPanelScrollApi => {
+  const { scrollPositionsByPageId } = context
+
+  const restoreScroller = (pageCacheId: string): void => {
+    const positions = scrollPositionsByPageId.get(pageCacheId)
+    if (!positions) return
+
+    for (const [selector, position] of positions) {
+      const element = resolveScrollElement(selector)
+      if (element) {
+        element.scrollTop = position.top
+        element.scrollLeft = position.left
+      }
     }
   }
-}
 
-/** 保存指定页面的滚动位置 */
-export const saveScroller = (pageCacheId: string) => {
-  const positions = scrollPositionsByPageId.get(pageCacheId)
-  if (!positions) return
-  for (const sel of positions.keys()) {
-    const el = document.querySelector(sel) as HTMLElement | null
-    positions.set(sel, {
-      top: el?.scrollTop ?? 0,
-      left: el?.scrollLeft ?? 0
-    })
+  const saveScroller = (pageCacheId: string): void => {
+    const positions = scrollPositionsByPageId.get(pageCacheId)
+    if (!positions) return
+
+    for (const selector of positions.keys()) {
+      const element = resolveScrollElement(selector)
+      positions.set(selector, {
+        top: element?.scrollTop ?? 0,
+        left: element?.scrollLeft ?? 0
+      })
+    }
   }
-}
 
-/** 移除指定页面的滚动记录 */
-export const removeScroller = (pageCacheId: string) => {
-  const positions = scrollPositionsByPageId.get(pageCacheId)
-  if (positions) {
+  const removeScroller = (pageCacheId: string): void => {
+    const positions = scrollPositionsByPageId.get(pageCacheId)
+    if (!positions) return
+
     positions.clear()
     scrollPositionsByPageId.delete(pageCacheId)
   }
-}
 
-/** 为页面注册需要记录滚动位置的选择器 */
-export const addPageScroller = (pageCacheId: string, ...selectorIds: string[]) => {
-  if (!scrollPositionsByPageId.has(pageCacheId)) {
-    scrollPositionsByPageId.set(pageCacheId, new Map<string, { top: number; left: number }>())
+  const addPageScroller = (pageCacheId: string, ...selectorIds: string[]): void => {
+    if (!scrollPositionsByPageId.has(pageCacheId)) {
+      scrollPositionsByPageId.set(pageCacheId, new Map())
+    }
+    const positions = scrollPositionsByPageId.get(pageCacheId)!
+    for (const selector of selectorIds) {
+      positions.set(selector, { top: 0, left: 0 })
+    }
   }
-  const positions = scrollPositionsByPageId.get(pageCacheId)!
-  for (const sel of selectorIds) {
-    positions.set(sel, { top: 0, left: 0 })
+
+  return {
+    restoreScroller,
+    saveScroller,
+    removeScroller,
+    addPageScroller
   }
 }

package/src/lib/hooks/tabPanel/session.ts

@@ -1,33 +1,95 @@
 /**
  * tabPanel/session - Session 持久化
  *
- * 职责：将当前激活标签保存到 sessionStorage，刷新后恢复
+ * 职责：基于当前 StackTabsRuntimeContext 将当前激活标签保存到 sessionStorage，刷新后恢复。
  */
-import type { ITabItem } from '../../model/TabModel'
+import type { ITabItem, ITabPage } from '../../model/TabModel'
 import { Stack } from '../../model/TabModel'
-import type { ITabPage } from '../../model/TabModel'
-import { SESSION_TAB_NAME, sessionPrefix } from './state'
+import { isRecord } from '../../utils/typeGuards'
+import type { StackTabsRuntimeContext } from '../stackTabsContext'
+import { SESSION_TAB_NAME } from './state'
 
-/** 获取 sessionStorage 的 key */
-export const getSessionKey = () => sessionPrefix + SESSION_TAB_NAME
+const isRestoredTab = (value: unknown): value is ITabItem =>
+  isRecord(value) &&
+  typeof value.id === 'string' &&
+  typeof value.title === 'string' &&
+  typeof value.closable === 'boolean' &&
+  typeof value.refreshable === 'boolean' &&
+  typeof value.iframe === 'boolean' &&
+  typeof value.active === 'boolean' &&
+  value.pages instanceof Stack
 
-/** 将当前激活的标签保存到 sessionStorage */
-export const saveActiveTabToSession = (tab: ITabItem) => {
-  if (!tab.id) return
-  window.sessionStorage.setItem(getSessionKey(), JSON.stringify(tab))
+export interface TabPanelSessionApi {
+  getSessionKey: () => string
+  saveActiveTabToSession: (tab: ITabItem) => void
+  clearSession: () => void
+  restoreActiveTabSession: (storedJson: string | null) => void
+  restoreTabFromSession: (storedJson: string | null) => ITabItem | null
 }
 
-/** 清除 sessionStorage 中的激活标签 */
-export const clearSession = () => {
-  window.sessionStorage.removeItem(getSessionKey())
-}
+export const createTabPanelSession = (context: StackTabsRuntimeContext): TabPanelSessionApi => {
+  const getSessionKey = (): string => context.sessionPrefix.value + SESSION_TAB_NAME
+  let pendingWrite: { tab: ITabItem; version: number } | null = null
+  let writeVersion = 0
+  let writeScheduled = false
+
+  const flushPendingWrite = () => {
+    writeScheduled = false
+    const write = pendingWrite
+    pendingWrite = null
+    if (!write || write.version !== writeVersion) return
+    window.sessionStorage.setItem(getSessionKey(), JSON.stringify(write.tab))
+  }
+
+  const invalidatePendingWrite = () => {
+    writeVersion++
+    pendingWrite = null
+  }
+
+  const saveActiveTabToSession = (tab: ITabItem): void => {
+    if (!tab.id) return
+    pendingWrite = { tab, version: ++writeVersion }
+    if (writeScheduled) return
+    writeScheduled = true
+    queueMicrotask(flushPendingWrite)
+  }
+
+  const clearSession = (): void => {
+    invalidatePendingWrite()
+    window.sessionStorage.removeItem(getSessionKey())
+  }
+
+  const restoreActiveTabSession = (storedJson: string | null): void => {
+    if (storedJson === null) {
+      clearSession()
+      return
+    }
+    invalidatePendingWrite()
+    window.sessionStorage.setItem(getSessionKey(), storedJson)
+  }
+
+  const restoreTabFromSession = (storedJson: string | null): ITabItem | null => {
+    if (storedJson == null) return null
+    try {
+      const restored = JSON.parse(storedJson, (key, value) =>
+        key === 'pages' && Array.isArray(value) ? new Stack<ITabPage>(value) : value
+      )
+      if (!isRestoredTab(restored)) {
+        clearSession()
+        return null
+      }
+      return restored as ITabItem
+    } catch {
+      clearSession()
+      return null
+    }
+  }
 
-/** 从 sessionStorage 解析恢复的标签（含 Stack 反序列化） */
-export const restoreTabFromSession = (
-  storedJson: string | null
-): ITabItem | null => {
-  if (storedJson == null) return null
-  return JSON.parse(storedJson, (k, v) =>
-    k === 'pages' ? new Stack<ITabPage>(v) : v
-  ) as ITabItem
+  return {
+    getSessionKey,
+    saveActiveTabToSession,
+    clearSession,
+    restoreActiveTabSession,
+    restoreTabFromSession
+  }
 }

package/src/lib/hooks/tabPanel/state.ts

@@ -1,52 +1,49 @@
 /**
- * tabPanel/state - 标签页核心共享状态
+ * tabPanel/state - 标签页运行时状态 factory
  *
- * 职责：集中管理 tabs、caches、components、驱逐集合、滚动位置等
- * 被 useTabPanel、evict、scroll、session 导入使用
+ * 职责：创建 tabs、caches、components、驱逐集合、滚动位置等运行时状态。
+ * 注意：本文件不导出模块级可变状态；每个 Vue app 只有一个 StackTabsRuntimeContext 持有这些状态。
  */
+import type { DefineComponent, Ref, ShallowRef } from 'vue'
+import { ref, shallowRef } from 'vue'
 import type { ITabItem } from '../../model/TabModel'
-import { ref } from 'vue'
 
-/** 当前打开的标签列表（含每个标签的页面栈） */
-export const tabs = ref<ITabItem[]>([])
-/** 初始化时传入的默认标签（用于对比 session 恢复） */
-export const defaultTabs: ITabItem[] = []
-/** keep-alive include 数组，与 Vue 的 keep-alive :include 绑定 */
-export const caches = ref<string[]>([])
-/** 页面缓存 ID -> 包装后的 DefineComponent */
-export const components = new Map<string, import('vue').DefineComponent>()
-/** 待驱逐的页面缓存 ID 集合 */
-export const cacheIdsToEvict = new Set<string>()
-/** 待驱逐的标签 ID 集合 */
-export const tabIdsToEvict = new Set<string>()
-/** 刷新计数器，变更时触发 component :key 变化 */
-export const refreshKey = ref<number>(0)
-/** 刷新时临时加入 keep-alive exclude 的缓存 ID */
-export const excludedCacheIdsForRefresh = ref<string[]>([])
-/** pageCacheId -> Map<selector, { top, left }> 滚动位置存储 */
-export const scrollPositionsByPageId = new Map<string, Map<string, { top: number; left: number }>>()
-/** 是否已完成初始化 */
-export const isInitialized = ref<boolean>(false)
-
-/** sessionStorage 中存储当前激活标签的 key 前缀 */
-export const SESSION_TAB_NAME = 'stacktab-active-tab'
+export interface ScrollPosition {
+  top: number
+  left: number
+}
 
-/** iframe 标签 tabId -> 刷新序号，变更时触发 iframe 重载 */
-export const iframeRefreshKeys = ref<Record<string, number>>({})
+export interface TabPanelRuntimeState {
+  tabs: Ref<ITabItem[]>
+  defaultTabs: Ref<ITabItem[]>
+  caches: ShallowRef<string[]>
+  components: Map<string, DefineComponent>
+  cacheIdsToEvict: Set<string>
+  tabIdsToEvict: Set<string>
+  refreshKey: Ref<number>
+  scrollPositionsByPageId: Map<string, Map<string, ScrollPosition>>
+  isInitialized: Ref<boolean>
+  iframeRefreshKeys: Ref<Record<string, number>>
+  maxTabCount: Ref<number>
+  useGlobalScroll: Ref<boolean>
+  sessionPrefix: Ref<string>
+}
 
-/** 最大标签数量，0 表示不限制 */
-export let maxTabCount = 0
-/** 是否使用页面级滚动 */
-export let useGlobalScroll = false
-/** sessionStorage key 前缀 */
-export let sessionPrefix = ''
+/** sessionStorage 中存储当前激活标签的 key 后缀 */
+export const SESSION_TAB_NAME = 'stacktab-active-tab'
 
-export const setMaxTabCount = (n: number) => {
-  maxTabCount = n
-}
-export const setUseGlobalScroll = (v: boolean) => {
-  useGlobalScroll = v
-}
-export const setSessionPrefix = (p: string) => {
-  sessionPrefix = p
-}
+export const createTabPanelRuntimeState = (): TabPanelRuntimeState => ({
+  tabs: ref<ITabItem[]>([]) as Ref<ITabItem[]>,
+  defaultTabs: ref<ITabItem[]>([]) as Ref<ITabItem[]>,
+  caches: shallowRef<string[]>([]),
+  components: new Map<string, DefineComponent>(),
+  cacheIdsToEvict: new Set<string>(),
+  tabIdsToEvict: new Set<string>(),
+  refreshKey: ref<number>(0),
+  scrollPositionsByPageId: new Map<string, Map<string, ScrollPosition>>(),
+  isInitialized: ref<boolean>(false),
+  iframeRefreshKeys: ref<Record<string, number>>({}),
+  maxTabCount: ref<number>(0),
+  useGlobalScroll: ref<boolean>(false),
+  sessionPrefix: ref<string>('')
+})