xn-vue3-router-tabs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,327 @@
+# xn-vue3-router-tabs
+
+为 Vue 3 + Vue Router 4 提供多页签能力的插件。
+
+- 零额外依赖（仅 peerDep: vue + vue-router）
+- 配置全部收口在路由 `meta` 中，不侵入业务代码
+- 内置 KeepAlive 缓存，切换 tab 不重新加载页面
+- 提供无样式 `<TabBar>` 组件，UI 完全由你控制
+
+---
+
+## 安装
+
+```bash
+npm install xn-vue3-router-tabs
+# 或
+pnpm add xn-vue3-router-tabs
+```
+
+---
+
+## 快速开始
+
+### 1. 安装插件（`main.ts`）
+
+**必须在 `app.use(router)` 之后安装。**
+
+```typescript
+import { createApp } from 'vue'
+import { createTabPlugin } from 'xn-vue3-router-tabs'
+import App from './App.vue'
+import { router } from './router'
+
+const app = createApp(App)
+app.use(router)
+app.use(createTabPlugin({
+  homePath: '/dashboard',   // 关闭最后一个 tab 时的兜底页
+  maxTabs: 10,              // 最大 tab 数（可选，默认不限）
+  closeStrategy: 'last-visited', // 关闭当前 tab 后的跳转策略（默认）
+}))
+app.mount('#app')
+```
+
+### 2. 配置路由 meta
+
+所有路由默认纳入多页签管理，只有以下情况需要配置 `meta`：
+
+```typescript
+const routes = [
+  // 不纳入管理（登录页、404 页等）
+  { path: '/login', meta: { tab: false } },
+
+  // 自定义标题（字符串）
+  { path: '/list', meta: { title: '采购列表' } },
+
+  // 动态标题（函数）—— path 传参，不同 id 自动产生独立 tab
+  {
+    path: '/detail/:id',
+    meta: { title: (route) => `单据 ${route.params.id}` },
+  },
+
+  // query 传参，不同 id 产生独立 tab（依赖 fullPath 作为默认 key）
+  {
+    path: '/order',
+    meta: { title: (route) => `订单 ${route.query.id}` },
+  },
+
+  // 两条路由共用同一个 tab（互相替换，而非新建）
+  {
+    path: '/purchase/new',
+    meta: { tabKey: '/purchase/list', title: '采购列表' },
+  },
+  {
+    path: '/purchase/list',
+    meta: { title: '采购列表' },
+  },
+]
+```
+
+### 3. 布局组件（`Layout.vue`）
+
+用 `<RouterViewTab>` 替换 `<RouterView>`，用 `<TabBar>` 渲染标签栏：
+
+```vue
+<template>
+  <!-- 标签栏：通过 slot 完全自定义每个 tab 的渲染 -->
+  <div class="tab-bar">
+    <TabBar v-slot="{ tab, isActive, close, refresh }">
+      <div
+        class="tab"
+        :class="{ active: isActive }"
+        @click="router.push(tab.route.fullPath)"
+      >
+        <span>{{ tab.title }}</span>
+        <button @click.stop="refresh()">刷新</button>
+        <button @click.stop="close()">关闭</button>
+      </div>
+    </TabBar>
+  </div>
+
+  <!-- 页面内容：内置 KeepAlive，切换 tab 不重新加载 -->
+  <RouterViewTab />
+</template>
+
+<script setup lang="ts">
+import { RouterViewTab, TabBar } from 'xn-vue3-router-tabs'
+import { useRouter } from 'vue-router'
+
+const router = useRouter()
+</script>
+```
+
+---
+
+## API
+
+### `createTabPlugin(options?)`
+
+创建插件实例。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `homePath` | `string` | `'/'` | 关闭最后一个 tab 或 `closeAll()` 后的跳转页 |
+| `maxTabs` | `number` | 不限 | 最大 tab 数，超出时自动移除最久未访问的 |
+| `closeStrategy` | `CloseStrategy` | `'last-visited'` | 关闭当前 tab 后的跳转策略 |
+| `getTabKey` | `(route) => string` | — | 全局 tabKey 计算函数（meta.tabKey 优先） |
+| `getTitle` | `(route) => string` | — | 全局 title 计算函数（meta.title 优先） |
+| `beforeClose` | `(tab: Tab) => boolean \| Promise<boolean>` | — | 全局关闭守卫，返回 `false` 阻止关闭 |
+
+**CloseStrategy 可选值：**
+
+| 值 | 行为 |
+|----|------|
+| `'last-visited'` | 跳转到最近访问的其他 tab |
+| `'previous'` | 跳转到列表中左侧相邻的 tab |
+| `'next'` | 跳转到列表中右侧相邻的 tab |
+| `'home'` | 跳转到 `homePath` |
+
+---
+
+### `useTabs()`
+
+在组件中调用，返回标签状态和操作方法。
+
+```typescript
+const {
+  tabs,          // Readonly<Tab[]>    — 响应式标签列表
+  activeKey,     // Readonly<Ref<string>> — 当前激活 tab 的 key
+  activeTab,     // ComputedRef<Tab | undefined> — 当前激活的 tab 对象
+  close,         // (key: string) => Promise<void>
+  refresh,       // (key?: string) => void
+  closeOthers,   // (key?: string) => Promise<void>
+  closeAll,      // () => Promise<void>
+  onBeforeClose, // (guard: BeforeCloseGuard) => void
+} = useTabs()
+```
+
+**Tab 对象结构：**
+
+```typescript
+interface Tab {
+  key: string                          // 唯一键
+  title: string                        // 显示标题
+  route: RouteLocationNormalizedLoaded // 对应路由快照
+  refreshCount: number                 // 内部刷新计数
+  createdAt: number                    // 创建时间戳
+  visitedAt: number                    // 最后访问时间戳
+}
+```
+
+---
+
+### `<RouterViewTab />`
+
+替代 `<RouterView>` 使用。内部封装了 `<KeepAlive>`，保证：
+
+- 切换 tab 时页面状态保留（不重新加载）
+- 不同参数的同路由各自拥有独立缓存实例
+- 调用 `refresh()` 时仅重建当前 tab 的组件，不影响其他 tab
+
+```vue
+<!-- 只需替换 RouterView，无需其他配置 -->
+<RouterViewTab />
+```
+
+---
+
+### `<TabBar>` 无样式组件
+
+通过 scoped slot 渲染每个 tab，插件不提供任何样式：
+
+```vue
+<TabBar v-slot="{ tab, isActive, close, refresh }">
+  <!-- tab: Tab 对象 -->
+  <!-- isActive: boolean 是否为当前激活 tab -->
+  <!-- close: () => void 关闭该 tab -->
+  <!-- refresh: () => void 刷新该 tab -->
+  <div :class="{ active: isActive }">
+    {{ tab.title }}
+  </div>
+</TabBar>
+```
+
+---
+
+### 路由 `meta` 配置
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `tab` | `boolean` | `false` 时排除该路由，默认 `true`（纳入管理） |
+| `tabKey` | `string \| (route) => string` | 自定义 tab 唯一键 |
+| `title` | `string \| (route) => string` | 自定义 tab 标题 |
+
+**tabKey 优先级：** `meta.tabKey` → `options.getTabKey` → `route.fullPath`
+
+**title 优先级：** `meta.title` → `options.getTitle` → `route.path`
+
+---
+
+## 使用场景示例
+
+### path 传参 — 不同 id 独立 tab（默认行为）
+
+```typescript
+// 路由配置
+{ path: '/detail/:id', meta: { title: (r) => `单据 ${r.params.id}` } }
+
+// 访问以下路由会产生 2 个独立 tab
+router.push('/detail/1001')
+router.push('/detail/1002')
+```
+
+### query 传参 — 不同 id 独立 tab（默认行为）
+
+```typescript
+// 路由配置（无需额外配置，fullPath 天然不同）
+{ path: '/order', meta: { title: (r) => `订单 ${r.query.id}` } }
+
+// 访问以下路由会产生 2 个独立 tab
+router.push('/order?id=A001')
+router.push('/order?id=A002')
+```
+
+### 强制单实例 — 任意参数共用同一个 tab
+
+```typescript
+// 所有详情页共用一个 tab，后打开的替换前一个
+{ path: '/detail/:id', meta: { tabKey: '/detail', title: (r) => `单据 ${r.params.id}` } }
+```
+
+### 两条路由共用同一个 tab
+
+```typescript
+// /purchase/new 和 /purchase/list 共用同一个 tab
+{ path: '/purchase/new',  meta: { tabKey: '/purchase/list', title: '新建采购单' } }
+{ path: '/purchase/list', meta: { title: '采购列表' } }
+```
+
+### 编程式操作
+
+```typescript
+const { close, refresh, closeOthers, closeAll, activeKey } = useTabs()
+
+// 关闭当前 tab
+close(activeKey.value)
+
+// 刷新当前 tab
+refresh()
+
+// 关闭其他所有 tab，保留当前
+closeOthers()
+
+// 关闭全部并跳转 homePath
+closeAll()
+```
+
+---
+
+## 关闭守卫（beforeClose）
+
+在页面有未保存修改时拦截 tab 关闭，支持组件级和全局级两种方式。
+
+### 组件级守卫 — `onBeforeClose`
+
+在页面组件内注册，组件销毁时自动解除：
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { useTabs } from 'xn-vue3-router-tabs'
+
+const { onBeforeClose } = useTabs()
+const hasUnsavedChanges = ref(false)
+
+onBeforeClose(() => {
+  if (hasUnsavedChanges.value) {
+    return window.confirm('有未保存的修改，确定关闭？')
+  }
+  return true
+})
+</script>
+```
+
+### 全局守卫 — 插件选项 `beforeClose`
+
+在插件安装时配置，应用于所有 tab：
+
+```typescript
+app.use(createTabPlugin({
+  beforeClose: async (tab) => {
+    // 可结合后端接口判断
+    return true
+  },
+}))
+```
+
+### 执行规则
+
+- **返回值**：`true`（允许关闭）、`false`（阻止关闭），支持 `Promise`
+- **执行顺序**：组件级守卫先执行 → 通过后 → 全局守卫再执行。任一返回 `false` 即阻止
+- **批量关闭**（`closeOthers` / `closeAll`）：逐个检查每个待关闭 tab，拒绝的保留，通过的关闭
+
+---
+
+## TypeScript 支持
+
+插件自动扩展 `vue-router` 的 `RouteMeta` 类型，路由配置中 `meta.tab`、`meta.tabKey`、`meta.title` 均有完整类型提示，无需手动声明。

package/dist/components/RouterViewTab.vue.d.ts

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

package/dist/components/TabBar.vue.d.ts

@@ -0,0 +1,16 @@
+declare function __VLS_template(): {
+    default?(_: {
+        tab: import('..').Tab;
+        isActive: boolean;
+        close: () => Promise<void>;
+        refresh: () => void;
+    }): any;
+};
+declare const __VLS_component: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, ReturnType<typeof __VLS_template>>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/composables/useTabs.d.ts

@@ -0,0 +1,3 @@
+import { UseTabsReturn } from '../types';
+
+export declare function useTabs(): UseTabsReturn;

package/dist/hooks.d.ts

@@ -0,0 +1,4 @@
+import { Router } from 'vue-router';
+import { TabPluginOptions, TabStoreContext } from './types';
+
+export declare function setupRouterHooks(router: Router, store: TabStoreContext, options: TabPluginOptions): void;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createTabPlugin } from './plugin';
+export { useTabs } from './composables/useTabs';
+export { default as RouterViewTab } from './components/RouterViewTab.vue';
+export { default as TabBar } from './components/TabBar.vue';
+export type { Tab, TabPluginOptions, TabStoreContext, UseTabsReturn, CloseStrategy, BeforeCloseGuard, } from './types';

package/dist/keys.d.ts

@@ -0,0 +1,5 @@
+import { InjectionKey } from 'vue';
+import { TabStoreContext } from './types';
+
+export declare const TAB_STORE_KEY: InjectionKey<TabStoreContext>;
+export declare const TAB_KEY: InjectionKey<string>;

package/dist/plugin.d.ts

@@ -0,0 +1,4 @@
+import { Plugin } from 'vue';
+import { TabPluginOptions } from './types';
+
+export declare function createTabPlugin(options?: TabPluginOptions): Plugin;

package/dist/resolver.d.ts

@@ -0,0 +1,5 @@
+import { RouteLocationNormalized } from 'vue-router';
+import { TabPluginOptions } from './types';
+
+export declare function resolveTabKey(route: RouteLocationNormalized, options: TabPluginOptions): string;
+export declare function resolveTitle(route: RouteLocationNormalized, options: TabPluginOptions): string;

package/dist/store.d.ts

@@ -0,0 +1,3 @@
+import { TabPluginOptions, TabStoreContext } from './types';
+
+export declare function createTabStore(options: TabPluginOptions): TabStoreContext;

package/dist/strategy.d.ts

@@ -0,0 +1,4 @@
+import { RouteLocationRaw } from 'vue-router';
+import { CloseStrategy, Tab } from './types';
+
+export declare function resolveNextRoute(closedKey: string, tabs: Tab[], strategy?: CloseStrategy, homePath?: string): RouteLocationRaw;

package/dist/types.d.ts

@@ -0,0 +1,86 @@
+import { ComputedRef, Ref } from 'vue';
+import { RouteLocationNormalized, RouteLocationNormalizedLoaded, RouteLocationRaw } from 'vue-router';
+
+declare module 'vue-router' {
+    interface RouteMeta {
+        /** false = 排除出多页签管理；默认 true（纳入） */
+        tab?: boolean;
+        /** 标签唯一键：字符串或根据 route 动态计算的函数 */
+        tabKey?: string | ((route: RouteLocationNormalized) => string);
+        /** 标签标题：字符串或根据 route 动态计算的函数 */
+        title?: string | ((route: RouteLocationNormalized) => string);
+    }
+}
+export type BeforeCloseGuard = () => boolean | Promise<boolean>;
+export interface Tab {
+    /** 唯一键，由 resolveTabKey 生成 */
+    key: string;
+    /** 显示标题 */
+    title: string;
+    /** 对应路由快照（导航完成时更新） */
+    route: RouteLocationNormalizedLoaded;
+    /** 刷新计数，用于驱动 KeepAlive 重建 */
+    refreshCount: number;
+    /** 创建时间戳 */
+    createdAt: number;
+    /** 最后访问时间戳，用于 last-visited 策略 */
+    visitedAt: number;
+}
+export type CloseStrategy = 'last-visited' | 'previous' | 'next' | 'home';
+export interface TabPluginOptions {
+    /**
+     * 全局 tabKey fallback。
+     * 优先级：meta.tabKey > getTabKey > route.fullPath
+     */
+    getTabKey?: (route: RouteLocationNormalized) => string;
+    /**
+     * 全局 title fallback。
+     * 优先级：meta.title > getTitle > route.path
+     */
+    getTitle?: (route: RouteLocationNormalized) => string;
+    /**
+     * 关闭当前 tab 后的跳转策略，默认 'last-visited'
+     */
+    closeStrategy?: CloseStrategy;
+    /**
+     * 兜底页路径，closeStrategy='home' 时或仅剩最后一个 tab 时跳转
+     */
+    homePath?: string;
+    /**
+     * 最大 tab 数，超出时自动移除 visitedAt 最早的 tab
+     */
+    maxTabs?: number;
+    /**
+     * 全局关闭守卫。返回 false 则阻止关闭。
+     */
+    beforeClose?: (tab: Tab) => boolean | Promise<boolean>;
+}
+export interface TabStoreContext {
+    tabs: Tab[];
+    activeKey: Ref<string>;
+    options: TabPluginOptions;
+    guardMap: Map<string, Set<BeforeCloseGuard>>;
+    addOrActivate: (tab: Omit<Tab, 'refreshCount' | 'createdAt' | 'visitedAt'>) => void;
+    remove: (key: string) => void;
+    setActive: (key: string) => void;
+    incrementRefresh: (key?: string) => void;
+}
+export interface UseTabsReturn {
+    /** 响应式标签列表（只读） */
+    tabs: Readonly<Tab[]>;
+    /** 当前激活的 tab key（只读） */
+    activeKey: Readonly<Ref<string>>;
+    /** 当前激活的 tab 对象 */
+    activeTab: ComputedRef<Tab | undefined>;
+    /** 关闭指定 tab，若为当前 tab 则按策略跳转 */
+    close: (key: string) => Promise<void>;
+    /** 刷新指定 tab，默认刷新当前 tab */
+    refresh: (key?: string) => void;
+    /** 关闭除指定 key 外的其他所有 tab */
+    closeOthers: (key?: string) => Promise<void>;
+    /** 关闭所有 tab 并跳转至兜底页 */
+    closeAll: () => Promise<void>;
+    /** 注册组件级关闭守卫，组件销毁时自动解除 */
+    onBeforeClose: (guard: BeforeCloseGuard) => void;
+}
+export type { RouteLocationRaw };

package/dist/xn-vue3-router-tabs.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("vue"),g=require("vue-router");function B(r,e){const n=r.meta.tabKey;return n!==void 0?typeof n=="function"?n(r):n:e.getTabKey?e.getTabKey(r):r.fullPath}function C(r,e){const n=r.meta.title;return n!==void 0?typeof n=="function"?n(r):n:e.getTitle?e.getTitle(r):r.path}function K(r,e,n){r.afterEach(o=>{if(o.meta.tab===!1){e.activeKey.value="";return}const l=B(o,n),d=C(o,n);e.addOrActivate({key:l,title:d,route:o})})}const _=Symbol("xn-vue3-router-tabs"),A=Symbol("xn-vue3-router-tabs-key");function R(r){const e=t.shallowReactive([]),n=t.ref(""),o=new Map;function l(c){const s=e.findIndex(u=>u.key===c.key);if(s>=0){e.splice(s,1,{...e[s],title:c.title,route:c.route,visitedAt:Date.now()}),n.value=c.key;return}if(e.push({...c,refreshCount:0,createdAt:Date.now(),visitedAt:Date.now()}),n.value=c.key,r.maxTabs&&e.length>r.maxTabs){let u=-1,p=1/0;for(let h=0;h<e.length-1;h++)e[h].visitedAt<p&&(p=e[h].visitedAt,u=h);u>=0&&e.splice(u,1)}}function d(c){const s=e.findIndex(u=>u.key===c);s>=0&&e.splice(s,1),o.delete(c)}function a(c){const s=e.findIndex(u=>u.key===c);s>=0&&(e.splice(s,1,{...e[s],visitedAt:Date.now()}),n.value=c)}function v(c){const s=c??n.value,u=e.findIndex(p=>p.key===s);u>=0&&e.splice(u,1,{...e[u],refreshCount:e[u].refreshCount+1})}return{tabs:e,activeKey:n,options:r,guardMap:o,addOrActivate:l,remove:d,setActive:a,incrementRefresh:v}}function P(r={}){return{install(e){const n=e.config.globalProperties.$router;if(!n){console.warn("[xn-vue3-router-tabs] vue-router is required. Make sure to install vue-router before xn-vue3-router-tabs.");return}const o=R(r);K(n,o,r),e.provide(_,o)}}}function I(r,e,n="last-visited",o="/"){const l=e.filter(a=>a.key!==r);if(l.length===0)return o;if(n==="last-visited")return[...l].sort((v,c)=>c.visitedAt-v.visitedAt)[0].route.fullPath;const d=e.findIndex(a=>a.key===r);if(n==="previous"){for(let a=d-1;a>=0;a--)if(e[a].key!==r)return e[a].route.fullPath;return l[0].route.fullPath}if(n==="next"){for(let a=d+1;a<e.length;a++)if(e[a].key!==r)return e[a].route.fullPath;return l[l.length-1].route.fullPath}return o}function T(){const r=t.inject(_);if(!r)throw new Error("[xn-vue3-router-tabs] useTabs() must be used inside a component that is a descendant of the app where createTabPlugin() was installed.");const e=r,n=g.useRouter(),{tabs:o,activeKey:l,options:d,guardMap:a}=e,v=t.computed(()=>o.find(i=>i.key===l.value)),c=t.inject(A,"");async function s(i){const y=a.get(i);if(y){for(const f of y)if(await f()===!1)return!1}if(d.beforeClose){const f=o.find(k=>k.key===i);if(f&&await d.beforeClose(f)===!1)return!1}return!0}function u(i){if(!c)return;const y=c;a.has(y)||a.set(y,new Set),a.get(y).add(i),t.getCurrentInstance()&&t.onUnmounted(()=>{const f=a.get(y);f&&(f.delete(i),f.size===0&&a.delete(y))})}async function p(i){if(!await s(i))return;if(i!==l.value){e.remove(i);return}const f=I(i,o,d.closeStrategy,d.homePath);await n.push(f)||e.remove(i)}function h(i){e.incrementRefresh(i)}async function w(i){const y=i??l.value;if(y!==l.value){const m=o.find(b=>b.key===y);if(m&&await n.push(m.route.fullPath))return}const f=o.filter(m=>m.key!==y),k=[];for(const m of f)await s(m.key)&&k.push(m.key);k.forEach(m=>e.remove(m))}async function x(){const i=[];for(const f of[...o])await s(f.key)&&i.push(f.key);i.length===0||i.includes(l.value)&&await n.push(d.homePath??"/")||i.forEach(f=>e.remove(f))}return{tabs:o,activeKey:l,activeTab:v,close:p,refresh:h,closeOthers:w,closeAll:x,onBeforeClose:u}}const S=t.defineComponent({__name:"RouterViewTab",setup(r){const e=g.useRoute(),{tabs:n,activeKey:o,activeTab:l}=T(),d=t.computed(()=>{var u;const s=((u=l.value)==null?void 0:u.refreshCount)??0;return`${o.value}@${s}`}),a=t.computed(()=>n.map(s=>`${s.key}@${s.refreshCount}`)),v=new Map;function c(s){const u=d.value;if(!v.has(u)){const h=t.shallowRef(s),w=o.value;v.set(u,{comp:t.defineComponent({name:u,setup(x,{attrs:i}){return t.provide(A,w),()=>t.h(h.value,i)}}),current:h})}const p=v.get(u);return p.current.value=s,p.comp}return t.watch(a,s=>{for(const u of v.keys())s.includes(u)||v.delete(u)}),(s,u)=>{const p=t.resolveComponent("RouterView");return t.openBlock(),t.createBlock(p,null,{default:t.withCtx(({Component:h})=>[(t.openBlock(),t.createBlock(t.KeepAlive,{include:a.value},[h&&t.unref(o)?(t.openBlock(),t.createBlock(t.resolveDynamicComponent(c(h)),{key:d.value})):t.createCommentVNode("",!0)],1032,["include"])),h&&!t.unref(o)?(t.openBlock(),t.createBlock(t.resolveDynamicComponent(h),{key:t.unref(e).fullPath})):t.createCommentVNode("",!0)]),_:1})}}}),E=t.defineComponent({__name:"TabBar",setup(r){const{tabs:e,activeKey:n,close:o,refresh:l}=T();return(d,a)=>(t.openBlock(!0),t.createElementBlock(t.Fragment,null,t.renderList(t.unref(e),v=>t.renderSlot(d.$slots,"default",{key:v.key,tab:v,isActive:v.key===t.unref(n),close:()=>t.unref(o)(v.key),refresh:()=>t.unref(l)(v.key)})),128))}});exports.RouterViewTab=S;exports.TabBar=E;exports.createTabPlugin=P;exports.useTabs=T;

package/dist/xn-vue3-router-tabs.js

@@ -0,0 +1,222 @@
+import { shallowReactive as E, ref as S, inject as K, computed as _, getCurrentInstance as $, onUnmounted as D, defineComponent as g, watch as M, resolveComponent as V, openBlock as k, createBlock as b, withCtx as O, KeepAlive as N, unref as w, resolveDynamicComponent as R, createCommentVNode as P, shallowRef as Y, provide as j, h as q, createElementBlock as z, Fragment as F, renderList as G, renderSlot as H } from "vue";
+import { useRouter as L, useRoute as U } from "vue-router";
+function W(r, e) {
+  const t = r.meta.tabKey;
+  return t !== void 0 ? typeof t == "function" ? t(r) : t : e.getTabKey ? e.getTabKey(r) : r.fullPath;
+}
+function J(r, e) {
+  const t = r.meta.title;
+  return t !== void 0 ? typeof t == "function" ? t(r) : t : e.getTitle ? e.getTitle(r) : r.path;
+}
+function Q(r, e, t) {
+  r.afterEach((n) => {
+    if (n.meta.tab === !1) {
+      e.activeKey.value = "";
+      return;
+    }
+    const c = W(n, t), f = J(n, t);
+    e.addOrActivate({ key: c, title: f, route: n });
+  });
+}
+const C = Symbol("xn-vue3-router-tabs"), I = Symbol("xn-vue3-router-tabs-key");
+function X(r) {
+  const e = E([]), t = S(""), n = /* @__PURE__ */ new Map();
+  function c(u) {
+    const s = e.findIndex((o) => o.key === u.key);
+    if (s >= 0) {
+      e.splice(s, 1, {
+        ...e[s],
+        title: u.title,
+        route: u.route,
+        visitedAt: Date.now()
+      }), t.value = u.key;
+      return;
+    }
+    if (e.push({
+      ...u,
+      refreshCount: 0,
+      createdAt: Date.now(),
+      visitedAt: Date.now()
+    }), t.value = u.key, r.maxTabs && e.length > r.maxTabs) {
+      let o = -1, y = 1 / 0;
+      for (let v = 0; v < e.length - 1; v++)
+        e[v].visitedAt < y && (y = e[v].visitedAt, o = v);
+      o >= 0 && e.splice(o, 1);
+    }
+  }
+  function f(u) {
+    const s = e.findIndex((o) => o.key === u);
+    s >= 0 && e.splice(s, 1), n.delete(u);
+  }
+  function a(u) {
+    const s = e.findIndex((o) => o.key === u);
+    s >= 0 && (e.splice(s, 1, { ...e[s], visitedAt: Date.now() }), t.value = u);
+  }
+  function d(u) {
+    const s = u ?? t.value, o = e.findIndex((y) => y.key === s);
+    o >= 0 && e.splice(o, 1, { ...e[o], refreshCount: e[o].refreshCount + 1 });
+  }
+  return { tabs: e, activeKey: t, options: r, guardMap: n, addOrActivate: c, remove: f, setActive: a, incrementRefresh: d };
+}
+function re(r = {}) {
+  return {
+    install(e) {
+      const t = e.config.globalProperties.$router;
+      if (!t) {
+        console.warn("[xn-vue3-router-tabs] vue-router is required. Make sure to install vue-router before xn-vue3-router-tabs.");
+        return;
+      }
+      const n = X(r);
+      Q(t, n, r), e.provide(C, n);
+    }
+  };
+}
+function Z(r, e, t = "last-visited", n = "/") {
+  const c = e.filter((a) => a.key !== r);
+  if (c.length === 0) return n;
+  if (t === "last-visited")
+    return [...c].sort((d, u) => u.visitedAt - d.visitedAt)[0].route.fullPath;
+  const f = e.findIndex((a) => a.key === r);
+  if (t === "previous") {
+    for (let a = f - 1; a >= 0; a--)
+      if (e[a].key !== r) return e[a].route.fullPath;
+    return c[0].route.fullPath;
+  }
+  if (t === "next") {
+    for (let a = f + 1; a < e.length; a++)
+      if (e[a].key !== r) return e[a].route.fullPath;
+    return c[c.length - 1].route.fullPath;
+  }
+  return n;
+}
+function B() {
+  const r = K(C);
+  if (!r)
+    throw new Error("[xn-vue3-router-tabs] useTabs() must be used inside a component that is a descendant of the app where createTabPlugin() was installed.");
+  const e = r, t = L(), { tabs: n, activeKey: c, options: f, guardMap: a } = e, d = _(() => n.find((i) => i.key === c.value)), u = K(I, "");
+  async function s(i) {
+    const h = a.get(i);
+    if (h) {
+      for (const l of h)
+        if (await l() === !1) return !1;
+    }
+    if (f.beforeClose) {
+      const l = n.find((m) => m.key === i);
+      if (l && await f.beforeClose(l) === !1)
+        return !1;
+    }
+    return !0;
+  }
+  function o(i) {
+    if (!u) return;
+    const h = u;
+    a.has(h) || a.set(h, /* @__PURE__ */ new Set()), a.get(h).add(i), $() && D(() => {
+      const l = a.get(h);
+      l && (l.delete(i), l.size === 0 && a.delete(h));
+    });
+  }
+  async function y(i) {
+    if (!await s(i)) return;
+    if (i !== c.value) {
+      e.remove(i);
+      return;
+    }
+    const l = Z(i, n, f.closeStrategy, f.homePath);
+    await t.push(l) || e.remove(i);
+  }
+  function v(i) {
+    e.incrementRefresh(i);
+  }
+  async function T(i) {
+    const h = i ?? c.value;
+    if (h !== c.value) {
+      const p = n.find((x) => x.key === h);
+      if (p && await t.push(p.route.fullPath))
+        return;
+    }
+    const l = n.filter((p) => p.key !== h), m = [];
+    for (const p of l)
+      await s(p.key) && m.push(p.key);
+    m.forEach((p) => e.remove(p));
+  }
+  async function A() {
+    const i = [];
+    for (const l of [...n])
+      await s(l.key) && i.push(l.key);
+    i.length === 0 || i.includes(c.value) && await t.push(f.homePath ?? "/") || i.forEach((l) => e.remove(l));
+  }
+  return {
+    tabs: n,
+    activeKey: c,
+    activeTab: d,
+    close: y,
+    refresh: v,
+    closeOthers: T,
+    closeAll: A,
+    onBeforeClose: o
+  };
+}
+const ne = /* @__PURE__ */ g({
+  __name: "RouterViewTab",
+  setup(r) {
+    const e = U(), { tabs: t, activeKey: n, activeTab: c } = B(), f = _(() => {
+      var o;
+      const s = ((o = c.value) == null ? void 0 : o.refreshCount) ?? 0;
+      return `${n.value}@${s}`;
+    }), a = _(
+      () => t.map((s) => `${s.key}@${s.refreshCount}`)
+    ), d = /* @__PURE__ */ new Map();
+    function u(s) {
+      const o = f.value;
+      if (!d.has(o)) {
+        const v = Y(s), T = n.value;
+        d.set(o, {
+          comp: g({
+            name: o,
+            setup(A, { attrs: i }) {
+              return j(I, T), () => q(v.value, i);
+            }
+          }),
+          current: v
+        });
+      }
+      const y = d.get(o);
+      return y.current.value = s, y.comp;
+    }
+    return M(a, (s) => {
+      for (const o of d.keys())
+        s.includes(o) || d.delete(o);
+    }), (s, o) => {
+      const y = V("RouterView");
+      return k(), b(y, null, {
+        default: O(({ Component: v }) => [
+          (k(), b(N, { include: a.value }, [
+            v && w(n) ? (k(), b(R(u(v)), { key: f.value })) : P("", !0)
+          ], 1032, ["include"])),
+          v && !w(n) ? (k(), b(R(v), {
+            key: w(e).fullPath
+          })) : P("", !0)
+        ]),
+        _: 1
+      });
+    };
+  }
+}), oe = /* @__PURE__ */ g({
+  __name: "TabBar",
+  setup(r) {
+    const { tabs: e, activeKey: t, close: n, refresh: c } = B();
+    return (f, a) => (k(!0), z(F, null, G(w(e), (d) => H(f.$slots, "default", {
+      key: d.key,
+      tab: d,
+      isActive: d.key === w(t),
+      close: () => w(n)(d.key),
+      refresh: () => w(c)(d.key)
+    })), 128));
+  }
+});
+export {
+  ne as RouterViewTab,
+  oe as TabBar,
+  re as createTabPlugin,
+  B as useTabs
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "xn-vue3-router-tabs",
+  "version": "0.1.0",
+  "description": "Multi-tab management plugin for Vue 3 + Vue Router 4",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anthropics/xn-vue3-router-tabs.git",
+    "directory": "packages/xn-vue3-router-tabs"
+  },
+  "keywords": [
+    "vue",
+    "vue3",
+    "vue-router",
+    "tabs",
+    "multi-tab",
+    "keep-alive",
+    "router-tab"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/xn-vue3-router-tabs.cjs",
+  "module": "./dist/xn-vue3-router-tabs.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/xn-vue3-router-tabs.js",
+      "require": "./dist/xn-vue3-router-tabs.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "vite build && vue-tsc --declaration --emitDeclarationOnly --outDir dist",
+    "dev": "vite build --watch",
+    "test": "vitest run",
+    "typecheck": "vue-tsc --noEmit"
+  },
+  "peerDependencies": {
+    "vue": "^3.0.0",
+    "vue-router": "^4.0.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.0.0",
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0",
+    "vite-plugin-dts": "^3.0.0",
+    "vitest": "^1.0.0",
+    "vue": "^3.4.0",
+    "vue-router": "^4.3.0",
+    "vue-tsc": "^2.0.0"
+  }
+}