vue-stack-tabs 2.2.0 → 2.4.0

package/README.en.md

@@ -509,6 +509,20 @@ You can specify refresh behavior via `iframeRefreshMode` when calling `openTab`:
 
 ---
 
+## Theming
+
+Every color and shadow is controlled by CSS variables. Light-theme defaults match the previous release, so no change is needed after upgrading. Re-skin by overriding variables:
+
+```css
+:root {
+  --stack-tab-accent: #4f46e5;
+  --stack-tab-accent-active: #4338ca;
+  --stack-tab-accent-contrast: #fff;
+}
+```
+
+A dark palette is built in and activates via `<html class="dark">`, `<html data-theme="dark">` or any `[data-theme="dark"]` container. See the [theming guide](https://jktantan.github.io/vue-stack-tabs/advance/theme) for the full variable list and scoped overrides.
+
 ## i18n
 
 Built-in languages: `zh-CN` (Chinese), `en` (English).

package/README.md

@@ -513,6 +513,20 @@ window.addEventListener('message', (ev) => {
 
 ---
 
+## 🎨 主题定制
+
+组件颜色与阴影全部由 CSS 变量控制，浅色默认值与旧版完全一致，升级后无需改动。直接覆盖变量即可换肤：
+
+```css
+:root {
+  --stack-tab-accent: #4f46e5;
+  --stack-tab-accent-active: #4338ca;
+  --stack-tab-accent-contrast: #fff;
+}
+```
+
+深色主题内置，支持 `<html class="dark">`、`<html data-theme="dark">` 或任意 `[data-theme="dark"]` 容器。完整变量清单与覆盖方式见[主题定制文档](https://jktantan.github.io/vue-stack-tabs/zh/advance/theme)。
+
 ## 🌍 国际化
 
 内置语言：`zh-CN`（中文）、`en`（英文）。

package/dist/StackTabs.vue.d.ts

@@ -47,13 +47,13 @@ declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, {}, {}, {},
     onOnPageLoaded?: ((...args: any[]) => any) | undefined;
 }>, {
     contextmenu: boolean | object;
-    defaultTabs: ITabData[];
     max: number;
     space: number;
-    width: string;
     tabScrollMode: TabScrollMode;
     tabTransition: string | TransitionProps;
+    width: string;
     iframeLoadTimeout: number;
+    defaultTabs: ITabData[];
     homeTab: ITabData;
     pageTransition: string;
     pageTransitionBack: string;

package/dist/components/StackKeepAlive/StackCacheRenderer.vue.d.ts

@@ -7,8 +7,6 @@ interface StackCacheRendererProps {
 interface StackCacheRendererSlotProps {
     wrappedComponent: DefineComponent;
     activeCacheKey: string;
-    refreshKey: number;
-    activePageRefreshVersion: number;
     component?: VNode | null;
 }
 type __VLS_Slots = {

package/dist/hooks/stackTabsContext.d.ts

@@ -7,7 +7,6 @@ export declare const STACK_TABS_CONTEXT_UNAVAILABLE_MESSAGE = "VueStackTabs runt
 export declare const STACK_TABS_DUPLICATE_INSTANCE_MESSAGE = "VueStackTabs only supports one <VueStackTabs> instance per Vue app.";
 export interface StackTabsRuntimeContext {
     tabs: Ref<ITabItem[]>;
-    defaultTabs: Ref<ITabItem[]>;
     caches: ShallowRef<string[]>;
     components: Map<string, DefineComponent>;
     cacheIdsToEvict: Set<string>;

package/dist/hooks/tabPageContext.d.ts

@@ -0,0 +1,18 @@
+import { InjectionKey } from 'vue';
+export interface TabPageContext {
+    /** 当前页面所属的标签 id（旧实现中的 attrs.tId） */
+    tabId: string;
+    /** 当前页面的缓存 id，即 cacheName（旧实现中的 attrs.pId） */
+    pageId: string;
+}
+export declare const tabPageContextKey: InjectionKey<TabPageContext>;
+/**
+ * 解析当前页面上下文。
+ *
+ * 优先读取缓存包装组件 provide 的上下文；attrs / props 仅作为旧版
+ * cloneVNode 注入方式以及手工挂载场景的兼容回退。
+ *
+ * 返回值允许只包含其中一个字段：useTabLoading 只依赖 tabId，
+ * 旧代码或手工挂载可能只传了其中一个 id。
+ */
+export declare const resolveTabPageContext: () => Partial<TabPageContext> | null;

package/dist/hooks/tabPanel/evict.d.ts

@@ -5,12 +5,12 @@ export interface TabPanelEvictionApi {
     markTabPagesForEviction: (tab: {
         id: string;
         pages: {
-            list(): ITabPage[];
+            readonlyList(): readonly ITabPage[];
         };
     }) => void;
     markTabPagesForEvictionOnly: (tab: {
         pages: {
-            list(): ITabPage[];
+            readonlyList(): readonly ITabPage[];
         };
     }) => void;
     addCache: (cacheName: string) => void;

package/dist/hooks/tabPanel/scroll.d.ts

@@ -4,7 +4,5 @@ export interface TabPanelScrollApi {
     saveScroller: (pageCacheId: string) => void;
     removeScroller: (pageCacheId: string) => void;
     addPageScroller: (pageCacheId: string, ...selectorIds: string[]) => void;
-    /** 主动失效某页面的滚动元素缓存，例如外部强制刷新缓存页时 */
-    invalidateAutoScrollCache: (pageCacheId: string) => void;
 }
 export declare const createTabPanelScroll: (context: StackTabsRuntimeContext) => TabPanelScrollApi;

package/dist/hooks/tabPanel/state.d.ts

@@ -6,7 +6,6 @@ export interface ScrollPosition {
 }
 export interface TabPanelRuntimeState {
     tabs: Ref<ITabItem[]>;
-    defaultTabs: Ref<ITabItem[]>;
     caches: ShallowRef<string[]>;
     components: Map<string, DefineComponent>;
     cacheIdsToEvict: Set<string>;

package/dist/hooks/useIframeManager.d.ts

@@ -8,7 +8,7 @@ interface IframeLoadState {
 export interface UseIframeManagerOptions {
     tabs: Ref<ITabItem[]>;
     iframeRefreshKeys: Ref<Record<string, number>>;
-    iframeLoadTimeout: number;
+    iframeLoadTimeout: Ref<number>;
     t: (key: string) => string;
 }
 export declare function useIframeManager(options: UseIframeManagerOptions): {

package/dist/hooks/useScrollShadow.d.ts

@@ -1,7 +1,14 @@
 import { Ref } from 'vue';
 export interface UseScrollShadowOptions {
-    /** 容器元素的 ref，可以是 Ref<HTMLElement | null> 或 getter 函数 */
+    /** 滚动容器：用于监听 scroll / resize 并读取滚动尺寸 */
     target: Ref<HTMLElement | null> | (() => HTMLElement | null);
+    /**
+     * 阴影类挂载目标，默认与 target 相同。
+     * 当 target 参与 transform 动画（如刷新转场）时，应传入不参与动画的祖先
+     * （例如 .stack-tab__keep-alive-panel），否则 ::after 的绝对定位包含块会变化，
+     * 阴影会随动画错位或消失。
+     */
+    classTarget?: Ref<HTMLElement | null> | (() => HTMLElement | null);
     /**
      * 是否监听内容缩放/尺寸变化（默认 true）。
      * 启用后会用 ResizeObserver 监视目标尺寸，容器或子树尺寸变化都会重新计算阴影边界。
@@ -14,7 +21,9 @@ export interface UseScrollShadowOptions {
     edgeThreshold?: number;
 }
 export interface UseScrollShadowReturn {
-    /** 手动同步一次（用于内容变化/resize 后） */
+    /** 重新解析滚动/阴影目标并同步一次（用于 keep-alive 激活、DOM 重新挂载后） */
     sync: () => void;
+    /** 移除阴影类并取消待执行的 rAF（用于 keep-alive 失活） */
+    clear: () => void;
 }
 export declare const useScrollShadow: (options: UseScrollShadowOptions) => UseScrollShadowReturn;

package/dist/hooks/useTabEventBus.d.ts

@@ -10,6 +10,8 @@ declare module '@vue/runtime-core' {
 export declare enum TabEventType {
     PAGE_LOADING = "PAGE_LOADING",
     TAB_ACTIVE = "TAB_ACTIVE",
+    /** 请求标签栏将指定标签滚动到可视区域（不改变激活状态） */
+    TAB_SCROLL_TO = "TAB_SCROLL_TO",
     FORWARD = "FORWARD",
     BACKWARD = "BACKWARD",
     REFRESH_IFRAME_POSTMESSAGE = "REFRESH_IFRAME_POSTMESSAGE"
@@ -23,6 +25,9 @@ export interface TabEventPayloadMap extends Record<EventType, unknown> {
         id: string;
         isRoute?: boolean;
     };
+    [TabEventType.TAB_SCROLL_TO]: {
+        id: string;
+    };
     [TabEventType.FORWARD]: void;
     [TabEventType.BACKWARD]: void;
     [TabEventType.REFRESH_IFRAME_POSTMESSAGE]: string;

package/dist/hooks/useTabLoading.d.ts

@@ -2,7 +2,8 @@
  * useTabLoading - 标签内页面加载状态 Hook
  *
  * 职责：通过 PAGE_LOADING 事件控制 PageLoading 组件的显示/隐藏
- * 使用范围：标签内的页面组件（需有 tId 通过 attrs 传入）
+ * 使用范围：标签内的页面组件；tabId 由缓存包装组件 provide，
+ * 页面通过 tabPageContext 解析（兼容旧版 attrs / props 注入）。
  */
 declare const _default: () => {
     openTabLoading: () => void;

package/dist/hooks/useTabRouter.d.ts

@@ -3,15 +3,19 @@ import { RouteLocationPathRaw } from 'vue-router';
  * useTabRouter - 标签内路由 Hook
  *
  * 职责：在单个标签内实现「前进/后退」栈式导航，以及滚动位置的记录与恢复
- * 使用范围：仅在标签内的页面组件中使用，依赖 StackTabs 通过 cloneVNode 注入的 tId / pId
+ * 使用范围：仅在标签内的页面组件中使用；页面上下文由缓存包装组件 provide，
+ * 通过 tabPageContext 解析（兼容旧版 attrs / props 注入）。
  *
  * 主要 API：
  * - forward(to)             前进：push 新页面到该标签的 pages 栈
  * - backward(to, backQuery) 后退：pop 栈顶、驱逐缓存，跳转到新栈顶
  * - addScrollTarget(...)    注册需要记录滚动位置的选择器
+ * - tabId / pageId          当前页面所属标签与缓存页 id（只读）
  */
 export default function useTabRouter(): {
     forward: (to: RouteLocationPathRaw) => void;
     backward: (to: number | string, backQuery?: Record<string, unknown>) => boolean;
     addScrollTarget: (...selectors: string[]) => void;
+    tabId: string;
+    pageId: string;
 };

package/dist/model/TabModel.d.ts

@@ -11,22 +11,29 @@ export declare enum TabScrollMode {
     BUTTON = "button",
     BOTH = "both"
 }
-/** 标签栏滚动条拖拽时的临时状态 */
+/**
+ * @deprecated 标签栏拖拽内部已不再使用该类型；保留仅为兼容 2.x 的公开类型导出，
+ * 将在下一个大版本移除。
+ */
 export interface DragData {
     thumbLeft: number;
     startScrollLeft: number;
     startThumbLeft: number;
     startPageX: number;
 }
-/** 滚动条滑块计算所需的数据 */
+/**
+ * @deprecated 内部滚轮/滚动事件常量已不再使用该类型；保留仅为兼容 2.x 的公开类型导出，
+ * 将在下一个大版本移除。
+ */
+export type ScrollEvents = {
+    ScrollUpdate: void;
+};
+/** 滚动条滑块计算所需的数据（滚动过程中保持非响应式） */
 export interface ScrollData {
     clientWidth: number;
     scrollWidth: number;
     scrollLeft: number;
 }
-export type ScrollEvents = {
-    ScrollUpdate: void;
-};
 /** 打开标签时传入的完整数据（含 path、query） */
 export interface ITabData extends ITabBase {
     title: string;

package/dist/nuxt/module.mjs

@@ -11,7 +11,7 @@ var a = i({
 		a.options.runtimeConfig.public.vueStackTabs = { locale: i.locale }, n({ src: o("./runtime/plugin") }), e({
 			name: "VueStackTabs",
 			export: "VueStackTabs",
-			filePath: o("../index.ts")
+			filePath: o("../vue-stack-tabs.es.js")
 		}), t([
 			{
 				name: "useTabActions",