vue-stack-tabs 1.0.1 → 1.3.0

package/dist/src/lib/hooks/useTabPanel.d.ts

@@ -1,104 +1,47 @@
-import { ITabData, ITabItem, ITabPage } from '../model/TabModel';
+import { ITabData, ITabItem } from '../model/TabModel';
 import { DefineComponent, VNode } from 'vue';
 import { RouteLocationNormalizedLoaded } from 'vue-router';
 /** 规范化路径（nginx 等可能加尾部斜杠） */
 export declare const normalizePathForCache: (route: RouteLocationNormalizedLoaded) => string;
 declare const _default: () => {
-    tabs: import('vue').Ref<{
-        id: string;
-        closable: boolean;
-        refreshable: boolean;
-        iframe: boolean;
-        iframeRefreshMode?: import('..').IframeRefreshMode | undefined;
-        url?: string | undefined;
-        active: boolean;
-        pages: {
-            push: (element: ITabPage) => void;
-            pop: () => ITabPage | undefined;
-            peek: () => ITabPage | undefined;
-            isEmpty: () => boolean;
-            size: () => number;
-            clear: () => void;
-            list: () => ITabPage[];
-            toString: () => string;
-            toJSON: () => ITabPage[];
-        };
-        title: string;
-    }[], ITabItem[] | {
-        id: string;
-        closable: boolean;
-        refreshable: boolean;
-        iframe: boolean;
-        iframeRefreshMode?: import('..').IframeRefreshMode | undefined;
-        url?: string | undefined;
-        active: boolean;
-        pages: {
-            push: (element: ITabPage) => void;
-            pop: () => ITabPage | undefined;
-            peek: () => ITabPage | undefined;
-            isEmpty: () => boolean;
-            size: () => number;
-            clear: () => void;
-            list: () => ITabPage[];
-            toString: () => string;
-            toJSON: () => ITabPage[];
-        };
-        title: string;
-    }[]>;
-    caches: import('vue').Ref<string[], string[]>;
+    tabs: import('vue').Ref<ITabItem[], ITabItem[]>;
+    caches: import('vue').ShallowRef<string[]>;
     refreshKey: import('vue').Ref<number, number>;
-    excludedCacheIdsForRefresh: import('vue').Ref<string[], string[]>;
+    activeCacheKey: import('vue').Ref<string, string>;
+    activePageRefreshVersion: import('vue').ComputedRef<number>;
     isInitialized: import('vue').Ref<boolean, boolean>;
-    setMaxSize: (n: number) => void;
+    setMaxSize: (value: number) => void;
     canAddTab: () => boolean;
     initialize: (staticTabs: ITabData[]) => void;
     size: () => number;
-    active: (id: string, route?: boolean) => void;
+    active: (id: string, route?: boolean) => Promise<void | import('vue-router').NavigationFailure | undefined>;
+    getCacheName: () => string;
     destroy: () => void;
     reset: () => void;
     addCache: (cacheName: string) => void;
     removeCache: (cacheName: string) => void;
-    getTab: (id: string) => {
-        id: string;
-        closable: boolean;
-        refreshable: boolean;
-        iframe: boolean;
-        iframeRefreshMode?: import('..').IframeRefreshMode | undefined;
-        url?: string | undefined;
-        active: boolean;
-        pages: {
-            push: (element: ITabPage) => void;
-            pop: () => ITabPage | undefined;
-            peek: () => ITabPage | undefined;
-            isEmpty: () => boolean;
-            size: () => number;
-            clear: () => void;
-            list: () => ITabPage[];
-            toString: () => string;
-            toJSON: () => ITabPage[];
-        };
-        title: string;
-    } | null;
-    addTab: (tab: ITabItem) => Promise<boolean>;
+    getTab: (id: string) => ITabItem | null;
+    addTab: (tab: ITabItem) => void;
     removeTab: (id: string) => string;
     removeAllTabs: () => void;
     removeLeftTabs: (id: string) => void;
     removeRightTabs: (id: string) => void;
     removeOtherTabs: (id: string) => void;
     hasTab: (id: string) => boolean;
-    renewTab: (tab: ITabData) => void;
-    addPage: (route: RouteLocationNormalizedLoaded, component: VNode) => DefineComponent;
-    addComponent: (id: string, comp: DefineComponent) => Map<string, DefineComponent<{}, {}, {}, import('vue').ComputedOptions, import('vue').MethodOptions, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{}>>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>>;
-    getComponent: (id: string) => DefineComponent<{}, {}, {}, import('vue').ComputedOptions, import('vue').MethodOptions, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{}>>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any> | undefined;
+    renewTab: (tab: ITabData) => (() => void) | undefined;
+    addPage: (route: RouteLocationNormalizedLoaded, component?: VNode | null) => DefineComponent;
+    addComponent: (id: string, comp: DefineComponent) => Map<string, DefineComponent>;
+    getComponent: (id: string) => DefineComponent | undefined;
     removeComponent: (id: string) => boolean;
     markCacheForEviction: (cacheName: string) => void;
     evictMarkedCaches: () => void;
+    evictPageCache: (cacheName: string) => void;
     refreshTab: (id: string) => void;
     refreshAllTabs: () => void;
     iframeRefreshKeys: import('vue').Ref<Record<string, number>, Record<string, number>>;
     addPageScroller: (pageCacheId: string, ...selectorIds: string[]) => void;
-    setGlobalScroll: (v: boolean) => void;
+    setGlobalScroll: (value: boolean) => void;
     clearSession: () => void;
-    setSessionPrefix: (p: string) => void;
+    setSessionPrefix: (value: string) => void;
 };
 export default _default;

package/dist/src/lib/hooks/useTabRouter.d.ts

@@ -3,15 +3,15 @@ import { RouteLocationPathRaw } from 'vue-router';
  * useTabRouter - 标签内路由 Hook
  *
  * 职责：在单个标签内实现「前进/后退」栈式导航，以及滚动位置的记录与恢复
- * 使用范围：仅在标签内的页面组件中使用，依赖 router-view 传入的 tId、pId
+ * 使用范围：仅在标签内的页面组件中使用，依赖 StackTabs 通过 cloneVNode 注入的 tId / pId
  *
  * 主要 API：
- * - forward(to) 前进：push 新页面到该标签的 pages 栈
- * - backward(to, backQuery?) 后退：pop 栈顶、markCacheForEviction，跳转到新栈顶
- * - addScrollTarget(...selectors) 注册需要记录滚动位置的选择器
+ * - forward(to)             前进：push 新页面到该标签的 pages 栈
+ * - backward(to, backQuery) 后退：pop 栈顶、驱逐缓存，跳转到新栈顶
+ * - addScrollTarget(...)    注册需要记录滚动位置的选择器
  */
 export default function useTabRouter(): {
     forward: (to: RouteLocationPathRaw) => void;
-    backward: (to: number | string, backQuery?: object) => void;
+    backward: (to: number | string, backQuery?: Record<string, unknown>) => boolean;
     addScrollTarget: (...selectors: string[]) => void;
 };

package/dist/src/lib/i18n/index.d.ts

@@ -1,7 +1,9 @@
+export interface LocaleMessageOption {
+    locale: string;
+    messages?: Record<string, unknown>;
+}
+export declare const mergeLocaleMessages: (baseMessages: Record<string, Record<string, unknown>>, localeI18n?: LocaleMessageOption[]) => Record<string, Record<string, unknown>>;
 declare const _default: () => {
-    getI18n: (localeI18n?: {
-        locale: string;
-        messages: Record<string, unknown>;
-    }[]) => import('vue-i18n-lite').I18n;
+    getI18n: (localeI18n?: LocaleMessageOption[]) => import('vue-i18n-lite').I18n;
 };
 export default _default;

package/dist/src/lib/i18n/lang/en.d.ts

@@ -11,7 +11,12 @@ declare const _default: {
         restore: string;
         undefined: string;
         loading: string;
+        iframeTitle: string;
+        iframeLoadTimeout: string;
+        retry: string;
         openInNewWindow: string;
+        scrollLeft: string;
+        scrollRight: string;
     };
 };
 export default _default;

package/dist/src/lib/i18n/lang/zh-CN.d.ts

@@ -11,7 +11,12 @@ declare const _default: {
         restore: string;
         undefined: string;
         loading: string;
+        iframeTitle: string;
+        iframeLoadTimeout: string;
+        retry: string;
         openInNewWindow: string;
+        scrollLeft: string;
+        scrollRight: string;
     };
 };
 export default _default;

package/dist/src/lib/i18n/stackTabsLocale.d.ts

@@ -0,0 +1,2 @@
+/** 将指定的 locale 应用到 vue-stack-tabs 内部 i18n 实例 */
+export declare const applyStackTabsLocale: (changeLocale: (locale: string) => void, locale?: string) => void;

package/dist/src/lib/iframe-bridge.d.ts

@@ -0,0 +1,8 @@
+/**
+ * iframe-bridge 子入口（vue-stack-tabs/iframe-bridge）。
+ *
+ * 供 iframe 内部页面引用，不包含 Vue 组件和样式等副作用，
+ * 仅导出 postMessage 通信工具。
+ */
+export { MSG_OPEN_TAB, MSG_REFRESH, onRefreshRequest, postOpenTab } from './utils/iframeBridge';
+export type { IframeBridgeOptions, IframeOpenTabPayload, RefreshRequestOptions } from './utils/iframeBridge';

package/dist/src/lib/iframe.vue.d.ts

@@ -1,2 +1,3 @@
-declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
 export default _default;

package/dist/src/lib/index.d.ts

@@ -1,23 +1,22 @@
 import { App } from 'vue';
+import { LocaleMessageOption } from './i18n';
 import { default as StackTab } from './StackTabs.vue';
 import { default as IFrame } from './iframe.vue';
 import { default as useTabLoading } from './hooks/useTabLoading';
 import { default as useTabRouter } from './hooks/useTabRouter';
 import { default as useTabActions } from './hooks/useTabActions';
 import { default as TabHeaderButton } from './components/TabHeader/TabHeaderButton.vue';
+export type VueStackTabsPluginOptions = LocaleMessageOption[];
 export * from './model/TabModel';
 declare module '@vue/runtime-core' {
     interface GlobalComponents {
         VueStackTabs: typeof StackTab;
     }
 }
-export { IFrame, useTabActions, useTabLoading, useTabRouter, TabHeaderButton, StackTab };
+export { IFrame, useTabActions, useTabLoading, useTabRouter, TabHeaderButton, StackTab, StackTab as VueStackTabs };
 export { postOpenTab, onRefreshRequest, MSG_REFRESH, MSG_OPEN_TAB } from './utils/iframeBridge';
 export type { IframeOpenTabPayload } from './utils/iframeBridge';
 declare const _default: {
-    install(Vue: App, options?: {
-        locale: string;
-        messages: Record<string, unknown>;
-    }[]): void;
+    install(Vue: App, options?: VueStackTabsPluginOptions): void;
 };
 export default _default;

package/dist/src/lib/model/TabModel.d.ts

@@ -1,3 +1,4 @@
+import { LocationQueryRaw } from 'vue-router';
 /**
  * TabModel - 标签页数据模型
  *
@@ -30,7 +31,7 @@ export type ScrollEvents = {
 export interface ITabData extends ITabBase {
     title: string;
     path: string;
-    query?: Record<string, string>;
+    query?: LocationQueryRaw;
 }
 /** iframe 刷新方式：postMessage 由 iframe 内页自行刷新（不重建 DOM，动画正常）；reload 强制重载 iframe */
 export type IframeRefreshMode = 'postMessage' | 'reload';
@@ -60,53 +61,33 @@ export interface ITabPage {
     id: string;
     tabId: string;
     path: string;
-    query?: Record<string, string>;
+    query?: LocationQueryRaw;
+    /** 页面级刷新版本；仅影响当前页面的 keep-alive 缓存 key */
+    refreshVersion?: number;
+    /** 该页面从别的页面被后退唤醒时附带的临时闭包参数，不污染 URL */
+    _backParams?: Record<string, unknown>;
 }
-/** 右键菜单项：图标、标题、回调、禁用条件 */
+/** 右键菜单项：重复或动态菜单应提供稳定 key，避免 fallback 标题/图标重复 */
 export interface IContextMenu {
+    key?: string;
     icon?: string;
     title: string;
     callback(id: string): void;
     disabled: (tabData: ITabBase) => boolean;
 }
-/** 使用 Map 实现的栈结构，用于标签内的 pages 页面栈 */
+/** 数组实现的栈结构，用于标签内的 pages 页面栈 */
 export declare class Stack<T> {
-    private items;
+    protected items: T[];
     constructor(items?: T[]);
-    /**
-     * @description: 入栈
-     * @param {T} element 要入栈的元素
-     */
     push(element: T): void;
-    /**
-     * @description: 出栈
-     * @return {T} 返回出栈的元素
-     */
     pop(): T | undefined;
-    /**
-     * @description: 返回栈顶的元素
-     * @return {T}
-     */
     peek(): T | undefined;
-    /**
-     * @description: 返回栈是否为空
-     * @return {Boolean}
-     */
+    at(index: number): T | undefined;
     isEmpty(): boolean;
-    /**
-     * @description: 返回栈里的元素个数
-     * @return {Number}
-     */
     size(): number;
-    /**
-     * @description: 清空栈
-     */
     clear(): void;
     list(): T[];
-    /**
-     * @description: 覆盖Object默认的toString
-     * @return {String}
-     */
-    toString(): string;
+    readonlyList(): readonly T[];
     toJSON(): T[];
+    toString(): string;
 }

package/dist/src/lib/nuxt/module.d.ts

@@ -0,0 +1,6 @@
+export interface ModuleOptions {
+    /** 默认语言 */
+    locale?: string;
+}
+declare const _default: import('nuxt/schema').NuxtModule<ModuleOptions, ModuleOptions, false>;
+export default _default;

package/dist/src/lib/nuxt/runtime/plugin.client.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('nuxt/app').Plugin<Record<string, unknown>> & import('nuxt/app').ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/src/lib/nuxt/runtime/plugin.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('nuxt/app').Plugin<Record<string, unknown>> & import('nuxt/app').ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/src/lib/utils/iframeBridge.d.ts

@@ -1,3 +1,4 @@
+import { LocationQueryRaw } from 'vue-router';
 /**
  * iframe 与父窗口的 postMessage 桥接
  *
@@ -9,23 +10,30 @@
 export declare const MSG_REFRESH = "vue-stack-tabs:refresh";
 /** 打开标签消息：iframe -> 父，payload 为 ITabData */
 export declare const MSG_OPEN_TAB = "vue-stack-tabs:openTab";
+export interface IframeBridgeOptions {
+    targetOrigin?: string;
+}
+export interface RefreshRequestOptions {
+    allowedOrigins?: string[];
+}
 export interface IframeOpenTabPayload {
     id?: string;
     title: string;
     path: string;
-    query?: Record<string, string>;
+    query?: LocationQueryRaw;
     closable?: boolean;
     refreshable?: boolean;
     iframe?: boolean;
+    iframeRefreshMode?: 'postMessage' | 'reload';
 }
 /**
  * 在 iframe 内调用：向父窗口请求打开新标签
  * @param payload 标签数据，至少需 title、path
  */
-export declare function postOpenTab(payload: IframeOpenTabPayload): void;
+export declare function postOpenTab(payload: IframeOpenTabPayload, options?: IframeBridgeOptions): void;
 /**
  * 在 iframe 内调用：注册刷新监听，收到父窗口刷新指令时执行 callback
  * @param callback 默认 location.reload()，可自定义
  * @returns 取消监听的函数
  */
-export declare function onRefreshRequest(callback?: () => void): () => void;
+export declare function onRefreshRequest(callback?: () => void, options?: RefreshRequestOptions): () => void;

package/dist/src/lib/utils/stackTabsA11y.d.ts

@@ -0,0 +1,8 @@
+/**
+ * WAI-ARIA 无障碍 ID 生成工具。
+ * 为 tab/panel 元素生成符合 ARIA tablist 模式的关联 ID。
+ */
+/** 生成 tab 触发器的 DOM id，用于 aria-controls 关联 */
+export declare const getStackTabTabId: (tabId: string) => string;
+/** 生成 tab 面板的 DOM id，用于 aria-labelledby 关联 */
+export declare const getStackTabPanelId: (tabId: string) => string;

package/dist/src/lib/utils/stackTabsMessage.d.ts

@@ -0,0 +1,7 @@
+import { ITabData } from '../model/TabModel';
+type ManagedSourceChecker = (source: MessageEventSource | null) => boolean;
+/** 校验 MessageEvent 是否为合法的 openTab 请求，返回解析后的 ITabData 或 null */
+export declare const isStackTabsOpenTabMessage: (event: MessageEvent, isManagedSource: ManagedSourceChecker) => ITabData | null;
+/** 根据 iframe URL 计算安全的 postMessage targetOrigin，非法 URL 返回 null */
+export declare const getPostMessageTargetOrigin: (url: string, fallbackOrigin?: string) => string | null;
+export {};

package/dist/src/lib/utils/tabInfoEncoder.d.ts

@@ -1,19 +1,4 @@
 import { ITabBase } from '../model/TabModel';
-/**
- * 标签信息编解码器
- *
- * 职责：将标签元数据压缩为 URL query 可用的短字符串，用于 __tab 参数
- * 格式: id|title|iframe|closable|refreshable，压缩后写入 query.__tab
- */
-/**
- * 编码标签基础信息为压缩字符串（用于 query.__tab）
- * @param tabData 标签基础数据
- */
 export declare const encodeTabInfo: (tabData: ITabBase) => string;
-/** 从 query.__tab 解压并解析为 ITabBase */
 export declare const decodeTabInfo: (encoded: string) => ITabBase;
-/**
- * 根据 tabId + path + query 生成页面缓存 ID
- * 用于 keep-alive 的 include 和 exclude，需稳定且唯一
- */
-export declare const createPageId: (tabId: string, path: string, query: object) => string;
+export declare const createPageId: () => string;

package/dist/src/lib/utils/typeGuards.d.ts

@@ -0,0 +1,2 @@
+/** 类型守卫：判断值是否为非数组的普通对象 */
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;

package/dist/src/lib/utils/urlParser.d.ts

@@ -1,9 +1,18 @@
+import { LocationQueryRaw } from 'vue-router';
 /**
- * 判断是否为不可嵌入 iframe 的协议
+ * 判断标签 URL 是否允许进入 iframe/window.open/router 等 URL sink。
+ * 允许相对路径、http(s) URL 与 about:blank；拒绝其它 scheme。
+ */
+export declare function isAllowedTabUrl(url: string): boolean;
+/**
+ * 判断是否为不允许嵌入 iframe 的 URL
  * @param url - 待检查的 URL 字符串
- * @returns javascript:、data: 等返回 true
+ * @returns 非 allowlist URL 返回 true
  */
 export declare function isInvalidIframeUrl(url: string): boolean;
+/** 非法 URL 降级为 about:blank，避免进入 iframe/window.open 等 URL sink */
+export declare function toSafeTabUrl(url: string): string;
+export declare function decodeSafeTabUrl(encodedUrl: unknown): string;
 /**
  * 判断 URL 是否为跨域（相对路径或同源视为同域）
  * @param url - 待检查的 URL
@@ -15,5 +24,17 @@ export declare function isCrossOriginUrl(url: string): boolean;
  */
 export declare function parseUrl(uri: string): {
     path: string;
-    query: Record<string, string>;
+    query: LocationQueryRaw;
 };
+/** 浅克隆 LocationQueryRaw，避免引用共享导致的副作用 */
+export declare function cloneLocationQuery(query?: LocationQueryRaw): LocationQueryRaw;
+export interface CloneablePage {
+    query?: LocationQueryRaw;
+    _backParams?: Record<string, unknown>;
+}
+/** 深克隆页面对象的 query 和 _backParams，防止跨页面引用污染 */
+export declare function clonePage<T extends CloneablePage>(page: T): T;
+/** 忽略 __tab/__src/_back 等内部保留 key 后比较两个 query 是否等价 */
+export declare function isSameQueryIgnoringReserved(a?: LocationQueryRaw, b?: LocationQueryRaw): boolean;
+/** 移除 query 中的 vue-stack-tabs 保留参数（__tab、__src），返回干净的 query */
+export declare function omitStackTabsReservedQuery(query?: LocationQueryRaw): LocationQueryRaw;

package/dist/src/lib/versionLogger.d.ts

@@ -1,2 +1,3 @@
+/** 在浏览器控制台输出带样式的库版本标识 */
 declare const logVersion: (version: string) => void;
 export default logVersion;