vue-stack-tabs 1.3.1 → 1.4.2

package/README.ru.md

@@ -1,8 +1,16 @@
 # vue-stack-tabs
 
+[![npm version](https://img.shields.io/npm/v/vue-stack-tabs.svg)](https://www.npmjs.com/package/vue-stack-tabs)
+[![npm downloads](https://img.shields.io/npm/dm/vue-stack-tabs.svg)](https://www.npmjs.com/package/vue-stack-tabs)
+[![license](https://img.shields.io/npm/l/vue-stack-tabs.svg)](./LICENSE)
+[![minzipped size](https://img.shields.io/bundlephobia/minzip/vue-stack-tabs)](https://bundlephobia.com/package/vue-stack-tabs)
+[![docs](https://img.shields.io/badge/docs-GitHub%20Pages-377dff)](https://jktantan.github.io/vue-stack-tabs/)
+
 [中文](./README.md) | [English](./README.en.md) | **Русский**
 
-> Библиотека управления вкладками для Vue 3 на основе Vue Router. Реализует поведение TabPanel, аналогичное iframe, с использованием областей видимости Vue — **каждая вкладка имеет изолированную область компонентов**.
+**📖 [Документация](https://jktantan.github.io/vue-stack-tabs/) · 🎮 [Демо](https://jktantan.github.io/vue-stack-tabs/demo.html)**
+
+> Библиотека управления вкладками для Vue 3 на основе Vue Router. Она обеспечивает изоляцию вкладок, подобную iframe, через независимые области видимости Vue: каждая вкладка сохраняет собственный экземпляр страницы, кэш и стек навигации.
 
 ## Возможности
 
@@ -13,6 +21,7 @@
 - **Сохранение сессии** — восстановление последних активных вкладок после обновления браузера
 - **Запоминание позиции прокрутки** — автоматическое восстановление позиции прокрутки при переключении вкладок
 - **Контекстное меню** — встроенные действия закрытия/обновления
+- **Слоты** — кнопки слева/справа на панели вкладок, свои плейсхолдеры загрузки/ошибки iframe
 - **Интернационализация** — встроенные китайский и английский языки, расширяемо
 - **Модуль Nuxt 3/4** — работает из коробки
 
@@ -38,7 +47,7 @@ pnpm add vue-stack-tabs
 // main.ts
 import { createApp } from 'vue'
 import VueStackTabs from 'vue-stack-tabs'
-import 'vue-stack-tabs/dist/vue-stack-tabs.css'
+import 'vue-stack-tabs/dist/style.css'
 import App from './App.vue'
 import router from './router'
 
@@ -48,6 +57,8 @@ app.use(VueStackTabs)
 app.mount('#app')
 ```
 
+> `vue-stack-tabs` поддерживает только один экземпляр `<VueStackTabs>` на приложение Vue. Экспорт по умолчанию — плагин Vue для `app.use(VueStackTabs)`; если нужен локальный импорт компонента, используйте именованный экспорт ниже.
+
 ### 2. Настройка маршрутов
 
 Вкладки зависят от Vue Router. Необходим родительский маршрут для размещения `<VueStackTabs>`:
@@ -100,6 +111,12 @@ const defaultTabs: ITabData[] = [
 </script>
 ```
 
+Если нужен локальный импорт компонента, используйте именованный экспорт `VueStackTabs`; именованный экспорт `StackTab` сохранён как алиас совместимости:
+
+```ts
+import { VueStackTabs as VueStackTabsComponent } from 'vue-stack-tabs'
+```
+
 ### 4. Открытие вкладок
 
 ```ts
@@ -133,9 +150,9 @@ refreshTab('about')
 export default defineNuxtConfig({
   modules: ['vue-stack-tabs/nuxt'],
   vueStackTabs: {
-    locale: 'en-US'
+    locale: 'zh-CN' // встроенные варианты: 'zh-CN' | 'en'
   },
-  css: ['vue-stack-tabs/dist/vue-stack-tabs.css']
+  css: ['vue-stack-tabs/dist/style.css']
 })
 ```
 
@@ -152,7 +169,9 @@ export default defineNuxtConfig({
 <script setup lang="ts">
 import type { ITabData } from 'vue-stack-tabs'
 
-const defaultTabs: ITabData[] = [{ title: 'Главная', path: '/', closable: false, refreshable: true }]
+const defaultTabs: ITabData[] = [
+  { title: 'Главная', path: '/', closable: false, refreshable: true }
+]
 </script>
 ```
 
@@ -163,7 +182,9 @@ const defaultTabs: ITabData[] = [{ title: 'Главная', path: '/', closable:
 <template>
   <div>
     <h1>Главная</h1>
-    <button @click="openTab({ title: 'О приложении', path: '/about' })">Открыть страницу «О приложении»</button>
+    <button @click="openTab({ title: 'О приложении', path: '/about' })">
+      Открыть страницу «О приложении»
+    </button>
   </div>
 </template>
 
@@ -183,7 +204,7 @@ const { openTab } = useTabActions()
 
 ```ts
 import VueStackTabs from 'vue-stack-tabs'
-import 'vue-stack-tabs/dist/vue-stack-tabs.css'
+import 'vue-stack-tabs/dist/style.css'
 ```
 
 Для iframe-страниц используйте суб-вход без побочных эффектов стилей:
@@ -219,7 +240,7 @@ const off = onRefreshRequest(() => window.location.reload(), {
 />
 ```
 
-Sandbox по умолчанию сохраняет типичные возможности бизнес-страниц и ориентирован на совместимость, не на строгую изоляцию. Для строгой изоляции удалите `allow-same-origin` и продолжайте уменьшать токены sandbox по потребностям бизнеса.
+Sandbox по умолчанию сохраняет типичные возможности бизнес-страниц и ориентирован на совместимость, не на строгую изоляцию. Для строгой изоляции удалите `allow-same-origin` и продолжайте уменьшать токены sandbox по потребностям бизнеса. Если ваши страницы того же источника не могут работать под sandbox, можно передать пустую строку для отключения sandbox, но это снижает уровень изоляции.
 
 ---
 
@@ -233,26 +254,36 @@ Sandbox по умолчанию сохраняет типичные возмож
 import { useTabActions } from 'vue-stack-tabs'
 
 const {
-  openTab, // (tab: ITabData, renew?: boolean) => Promise<string>
+  openTab, // (tab: ITabData, renew?: boolean) => Promise<string | undefined>
   closeTab, // (id: string) => string
   closeAllTabs, // () => void
   refreshTab, // (id: string) => void
   refreshAllTabs, // () => void
   activeTab, // (id: string, isRoute?: boolean) => void
+  moveTab, // (id: string, targetIndex: number) => boolean
   reset, // () => void
-  tabs // Ref<ITabItem[]>
+  tabs, // Ref<ITabItem[]>
+  setIFramePath, // (path: string) => void
+  getWrapper, // ({ tabId?, pageId? }) => HTMLElement | undefined
+  openInNewWindow // (id: string) => void
 } = useTabActions()
 ```
 
-| Метод                  | Описание                                                                          |
-| ---------------------- | --------------------------------------------------------------------------------- |
-| `openTab(tab, renew?)` | Открыть новую вкладку. При `renew=true` очищает стек страниц и открывает заново   |
-| `closeTab(id)`         | Закрыть указанную вкладку, возвращает ID новой активной вкладки                    |
-| `closeAllTabs()`       | Закрыть все закрываемые вкладки                                                   |
-| `refreshTab(id)`       | Обновить указанную вкладку (заменяет ID кэша, пересоздаёт экземпляр компонента)      |
-| `refreshAllTabs()`     | Обновить все вкладки                                                              |
-| `activeTab(id)`        | Активировать указанную вкладку (переключить вкладку)                               |
-| `reset()`              | Закрыть все вкладки и сбросить состояние                                          |
+| Метод                             | Описание                                                                                                                             |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `openTab(tab, renew?)`            | Открыть новую вкладку. При `renew=true` очищает стек страниц и открывает заново                                                      |
+| `closeTab(id)`                    | Закрыть указанную вкладку, возвращает ID новой активной вкладки                                                                      |
+| `closeAllTabs()`                  | Закрыть все закрываемые вкладки                                                                                                      |
+| `refreshTab(id)`                  | Обновить указанную вкладку (заменяет ID кэша, пересоздаёт экземпляр компонента)                                                      |
+| `refreshAllTabs()`                | Обновить все вкладки                                                                                                                 |
+| `activeTab(id)`                   | Активировать указанную вкладку (переключить вкладку)                                                                                 |
+| `moveTab(id, targetIndex)`        | Переместить вкладку на указанный индекс; панель вкладок также поддерживает перетаскивание                                            |
+| `reset()`                         | Закрыть все вкладки и сбросить состояние                                                                                             |
+| `setIFramePath(path)`             | Установить путь маршрута-заглушки iframe (вызывается внутри компонента)                                                              |
+| `getWrapper({ tabId?, pageId? })` | Получить DOM-контейнер содержимого; без параметров вернёт первый контейнер, при нескольких вкладках передавайте `tabId` или `pageId` |
+| `openInNewWindow(id)`             | Открыть вкладку iframe в новом окне (fallback, если встраивание невозможно)                                                          |
+
+> Закрытие слева / справа / остальных — операции только контекстного меню, выполняются внутри `TabHeader`/`ContextMenu` через `useTabPanel`.
 
 ---
 
@@ -268,9 +299,9 @@ const { forward, backward, addScrollTarget } = useTabRouter()
 
 | Метод                       | Описание                                                    |
 | --------------------------- | ----------------------------------------------------------- |
-| `forward(to)`               | Перейти вперёд к новой странице внутри текущей вкладки       |
+| `forward(to)`               | Перейти вперёд к новой странице внутри текущей вкладки      |
 | `backward(to, backQuery?)`  | Вернуться назад внутри текущей вкладки                      |
-| `addScrollTarget(selector)` | Зарегистрировать CSS-селектор DOM для запоминания прокрутки  |
+| `addScrollTarget(selector)` | Зарегистрировать CSS-селектор DOM для запоминания прокрутки |
 
 #### forward
 
@@ -333,35 +364,67 @@ fetchData().finally(() => closeTabLoading())
 
 Свойства компонента `<VueStackTabs>`:
 
-| Свойство               | Тип                         | По умолчанию            | Описание                                                      |
-| ----------------------- | --------------------------- | ----------------------- | ------------------------------------------------------------- |
-| `iframePath`            | `string`                    | **Обязательно**         | Путь маршрута-заглушки для iframe                              |
-| `iframeSandbox`         | `string`                    | `allow-scripts allow-forms allow-popups allow-downloads allow-same-origin` | Политика sandbox для iframe; по умолчанию совместимость, не строгая изоляция — удалите `allow-same-origin` для строгой изоляции; пустая строка отключает sandbox (не рекомендуется) |
-| `iframeReferrerPolicy`  | `ReferrerPolicy`            | `strict-origin-when-cross-origin`                                          | Атрибут referrerpolicy для iframe                             |
-| `iframeAllow`           | `string`                    | `''`                                                                       | Атрибут allow для iframe, например `fullscreen`               |
-| `iframeLoadTimeout`     | `number`                    | `15000`                                                                    | Тайм-аут загрузки iframe в мс                                |
-| `defaultTabs`           | `ITabData[]`                | `[]`                    | Начальный список вкладок                                      |
-| `max`                   | `number`                    | `20`                    | Максимальное количество вкладок                                |
-| `contextmenu`           | `boolean \| object`         | `true`                  | Включить контекстное меню                                      |
-| `pageTransition`        | `string`                    | `'stack-tab-swap'`      | Имя анимации перехода при навигации вперёд                     |
-| `pageTransitionBack`    | `string`                    | `'stack-tab-swap-back'` | Имя анимации перехода при навигации назад                      |
-| `tabTransition`         | `string \| TransitionProps` | `'stack-tab-zoom'`      | Эффект перехода при добавлении/удалении вкладок                |
-| `tabScrollMode`         | `TabScrollMode`             | `'both'`                | Режим прокрутки панели вкладок: `'wheel'` / `'button'` / `'both'` |
-| `width`                 | `string`                    | `'100%'`                | Ширина контейнера                                              |
-| `height`                | `string`                    | `'100%'`                | Высота контейнера                                              |
-| `i18n`                  | `string`                    | `'zh-CN'`               | Локаль интернационализации                                     |
-| `globalScroll`          | `boolean`                   | `false`                 | Включить запоминание прокрутки на уровне страницы              |
-| `sessionPrefix`         | `string`                    | `''`                    | Префикс ключа sessionStorage                                  |
-| `iframeAllowedOrigins`  | `string[]`                  | Тот же источник         | Разрешённые источники для iframe postMessage                   |
+| Свойство               | Тип                         | По умолчанию                                                               | Описание                                                                                                                                                                            |
+| ---------------------- | --------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `iframePath`           | `string`                    | **Обязательно**                                                            | Путь маршрута-заглушки для iframe                                                                                                                                                   |
+| `iframeSandbox`        | `string`                    | `allow-scripts allow-forms allow-popups allow-downloads allow-same-origin` | Политика sandbox для iframe; по умолчанию совместимость, не строгая изоляция — удалите `allow-same-origin` для строгой изоляции; пустая строка отключает sandbox (не рекомендуется) |
+| `iframeReferrerPolicy` | `ReferrerPolicy`            | `strict-origin-when-cross-origin`                                          | Атрибут referrerpolicy для iframe                                                                                                                                                   |
+| `iframeAllow`          | `string`                    | `''`                                                                       | Атрибут allow для iframe, например `fullscreen`                                                                                                                                     |
+| `iframeLoadTimeout`    | `number`                    | `15000`                                                                    | Тайм-аут загрузки iframe в мс                                                                                                                                                       |
+| `defaultTabs`          | `ITabData[]`                | `[]`                                                                       | Начальный список вкладок                                                                                                                                                            |
+| `max`                  | `number`                    | `20`                                                                       | Максимальное количество вкладок                                                                                                                                                     |
+| `contextmenu`          | `boolean \| object`         | `true`                                                                     | Включить контекстное меню                                                                                                                                                           |
+| `pageTransition`       | `string`                    | `'stack-tab-swap'`                                                         | Имя анимации перехода при навигации вперёд                                                                                                                                          |
+| `pageTransitionBack`   | `string`                    | `'stack-tab-swap-back'`                                                    | Имя анимации перехода при навигации назад                                                                                                                                           |
+| `tabTransition`        | `string \| TransitionProps` | `'stack-tab-zoom'`                                                         | Эффект перехода при добавлении/удалении вкладок                                                                                                                                     |
+| `tabScrollMode`        | `TabScrollMode`             | `'both'`                                                                   | Режим прокрутки панели вкладок: `'wheel'` / `'button'` / `'both'`                                                                                                                   |
+| `space`                | `number`                    | `300`                                                                      | Шаг прокрутки панели вкладок (px)                                                                                                                                                   |
+| `width`                | `string`                    | `'100%'`                                                                   | Ширина контейнера                                                                                                                                                                   |
+| `height`               | `string`                    | `'100%'`                                                                   | Высота контейнера                                                                                                                                                                   |
+| `i18n`                 | `string`                    | `'zh-CN'`                                                                  | Локаль интернационализации, встроенные `'zh-CN'` / `'en'`                                                                                                                           |
+| `globalScroll`         | `boolean`                   | `false`                                                                    | Включить запоминание прокрутки на уровне страницы                                                                                                                                   |
+| `sessionPrefix`        | `string`                    | `''`                                                                       | Префикс ключа sessionStorage; полезно для нескольких экземпляров на одном источнике                                                                                                 |
+| `iframeAllowedOrigins` | `string[]`                  | `[]` (плюс текущий источник)                                               | Разрешённые источники для iframe postMessage                                                                                                                                        |
 
 ---
 
 ## События (Events)
 
-| Событие        | Параметры      | Описание                                      |
-| -------------- | -------------- | --------------------------------------------- |
-| `onActive`     | `(id: string)` | Срабатывает при активации вкладки              |
-| `onPageLoaded` | —              | Срабатывает при загрузке компонента страницы   |
+| Событие        | Параметры      | Описание                                     |
+| -------------- | -------------- | -------------------------------------------- |
+| `onActive`     | `(id: string)` | Срабатывает при активации вкладки            |
+| `onPageLoaded` | —              | Срабатывает при загрузке компонента страницы |
+
+```vue
+<VueStackTabs
+  iframe-path="/iframe"
+  @on-active="(id) => console.log('active:', id)"
+  @on-page-loaded="() => console.log('page loaded')"
+/>
+```
+
+---
+
+## Слоты
+
+| Слот            | Параметры слота  | Описание                                                             |
+| --------------- | ---------------- | -------------------------------------------------------------------- |
+| `leftButton`    | —                | Левая область панели вкладок, обычно с `TabHeaderButton`             |
+| `rightButton`   | —                | Правая область панели вкладок                                        |
+| `iframeLoading` | `{ tab }`        | Свой плейсхолдер загрузки для вкладки iframe                         |
+| `iframeError`   | `{ tab, retry }` | Свой плейсхолдер ошибки для вкладки iframe; `retry()` — перезагрузка |
+
+```vue
+<VueStackTabs iframe-path="/iframe">
+  <template #leftButton>
+    <TabHeaderButton title="Развернуть" @click="collapse = !collapse" />
+  </template>
+  <template #iframeError="{ tab, retry }">
+    <span>{{ tab.title }} не загрузилась</span>
+    <button @click="retry">Повторить</button>
+  </template>
+</VueStackTabs>
+```
 
 ---
 
@@ -451,23 +514,29 @@ window.addEventListener('message', (ev) => {
 
 ## Интернационализация
 
-Встроенные языки: `zh-CN` (китайский), `en-US` (английский).
+Встроенные языки: `zh-CN` (китайский), `en` (английский).
 
 ```ts
-// Переключить язык
-app.use(VueStackTabs, [{ locale: 'en-US' }])
+// Переключить язык через prop компонента
+// <VueStackTabs iframe-path="/iframe" i18n="en" />
+
+// Или при установке плагина
+app.use(VueStackTabs, [{ locale: 'en' }])
 ```
 
-Пользовательский языковой пакет:
+Пользовательский языковой пакет (`messages` — вложенный объект, глубоко сливается со встроенными языками):
 
 ```ts
 app.use(VueStackTabs, [
   {
     locale: 'ru-RU',
     messages: {
-      'VueStackTab.close': 'Закрыть',
-      'VueStackTab.refresh': 'Обновить'
-      // ...
+      VueStackTab: {
+        close: 'Закрыть',
+        reload: 'Обновить',
+        loading: 'Загрузка'
+        // ...
+      }
     }
   }
 ])
@@ -478,12 +547,14 @@ app.use(VueStackTabs, [
 ## Определения типов
 
 ```ts
+import type { LocationQueryRaw } from 'vue-router'
+
 /** Данные, передаваемые при открытии вкладки */
 interface ITabData {
   id?: string // ID вкладки (автоматически генерируемый UUID, если не указан)
   title: string // Заголовок вкладки
   path: string // Путь маршрута или URL iframe
-  query?: Record<string, string> // Параметры маршрута
+  query?: LocationQueryRaw // Параметры маршрута
   closable?: boolean // Можно ли закрыть (по умолчанию true)
   refreshable?: boolean // Можно ли обновить (по умолчанию true)
   iframe?: boolean // Является ли вкладкой iframe (по умолчанию false)
@@ -523,4 +594,4 @@ src/lib/
 
 ## Лицензия
 
-[LGPL-2.1](./LICENSE)
+[Apache-2.0](./LICENSE)

package/dist/{src/lib/StackTabs.vue.d.ts → StackTabs.vue.d.ts}

@@ -22,9 +22,9 @@ type __VLS_Props = {
     iframeAllow?: string;
     iframeLoadTimeout?: number;
 };
-declare var __VLS_10: {}, __VLS_13: {}, __VLS_34: {
+declare var __VLS_10: {}, __VLS_13: {}, __VLS_35: {
     tab: import('.').ITabItem;
-}, __VLS_36: {
+}, __VLS_37: {
     tab: import('.').ITabItem;
     retry: (frameId: string) => void;
 };
@@ -33,9 +33,9 @@ type __VLS_Slots = {} & {
 } & {
     rightButton?: (props: typeof __VLS_13) => any;
 } & {
-    iframeLoading?: (props: typeof __VLS_34) => any;
+    iframeLoading?: (props: typeof __VLS_35) => any;
 } & {
-    iframeError?: (props: typeof __VLS_36) => any;
+    iframeError?: (props: typeof __VLS_37) => any;
 };
 declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
     onActive: (...args: any[]) => void;
@@ -44,9 +44,9 @@ declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, {}, {}, {},
     onOnActive?: ((...args: any[]) => any) | undefined;
     onOnPageLoaded?: ((...args: any[]) => any) | undefined;
 }>, {
+    contextmenu: boolean | object;
     defaultTabs: ITabData[];
     max: number;
-    contextmenu: boolean | object;
     space: number;
     width: string;
     tabScrollMode: TabScrollMode;

package/dist/{src/lib/components → components}/ContextMenu/index.vue.d.ts

@@ -15,7 +15,7 @@ declare const __VLS_export: import('vue').DefineComponent<__VLS_Props, {}, {}, {
 }>, {
     left: number;
     top: number;
-    contextMenu: Array<IContextMenu>;
+    contextMenu: IContextMenu[];
     restoreFocusElement: HTMLElement | null;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;

package/dist/components/StackKeepAlive/emptyPlaceholder.d.ts

@@ -0,0 +1,3 @@
+import { DefineComponent } from 'vue';
+export declare const EmptyPlaceholderComponent: DefineComponent;
+export declare const getEmptyPlaceholderComponent: () => DefineComponent;

package/dist/{src/lib/components → components}/TabHeader/TabHeaderItem.vue.d.ts

@@ -1,15 +1,24 @@
 import { ITabItem } from '../../model/TabModel';
 type __VLS_Props = {
     item: ITabItem;
+    dropPosition?: 'before' | 'after';
 };
 declare const __VLS_export: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
     active: (...args: any[]) => void;
     close: (...args: any[]) => void;
     contextmenu: (...args: any[]) => void;
+    dragend: (...args: any[]) => void;
+    dragover: (...args: any[]) => void;
+    dragstart: (...args: any[]) => void;
+    drop: (...args: any[]) => void;
 }, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
     onActive?: ((...args: any[]) => any) | undefined;
     onClose?: ((...args: any[]) => any) | undefined;
     onContextmenu?: ((...args: any[]) => any) | undefined;
+    onDragend?: ((...args: any[]) => any) | undefined;
+    onDragover?: ((...args: any[]) => any) | undefined;
+    onDragstart?: ((...args: any[]) => any) | undefined;
+    onDrop?: ((...args: any[]) => any) | undefined;
 }>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/{src/lib/components → components}/TabHeader/index.vue.d.ts

@@ -7,19 +7,19 @@ type __VLS_Props = {
     contextmenu?: boolean | object;
     max?: number;
 };
-declare var __VLS_1: {}, __VLS_30: {};
+declare var __VLS_1: {}, __VLS_35: {};
 type __VLS_Slots = {} & {
     leftButton?: (props: typeof __VLS_1) => any;
 } & {
-    rightButton?: (props: typeof __VLS_30) => any;
+    rightButton?: (props: typeof __VLS_35) => any;
 };
 declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
     active: (...args: any[]) => void;
 }, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
     onActive?: ((...args: any[]) => any) | undefined;
 }>, {
-    max: number;
     contextmenu: boolean | object;
+    max: number;
     tabScrollMode: TabScrollMode;
     tabTransition: string | TransitionProps;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;

package/dist/{src/lib/hooks → hooks}/stackTabsContext.d.ts

@@ -39,11 +39,14 @@ export declare const stackTabsContextKey: InjectionKey<StackTabsRuntimeContext>;
 export declare const maximumKey: InjectionKey<Ref<boolean>>;
 /** 创建一个新的运行时上下文实例 */
 export declare const createStackTabsRuntimeContext: (options?: CreateStackTabsRuntimeContextOptions) => StackTabsRuntimeContext;
-/** 获取当前活跃的运行时上下文（模块级单例） */
+/**
+ * 获取非 App 容器下注册的兼容上下文。
+ * @deprecated App 内的 composable 必须依赖 provide/inject，不应使用这个回退。
+ */
 export declare const getActiveStackTabsRuntimeContext: () => StackTabsRuntimeContext | null;
 /** 注册运行时上下文，重复注册会在开发环境抛出错误 */
 export declare const registerStackTabsRuntimeContext: (context: StackTabsRuntimeContext, options?: RegisterStackTabsRuntimeContextOptions) => boolean;
 /** 注销运行时上下文，组件卸载时调用 */
 export declare const unregisterStackTabsRuntimeContext: (context: StackTabsRuntimeContext, options?: UnregisterStackTabsRuntimeContextOptions) => void;
-/** 解析当前可用的运行时上下文，优先使用 inject，回退到模块单例 */
+/** 解析当前可用的运行时上下文，优先使用 inject，兼容回退仅限非 App 容器。 */
 export declare const resolveStackTabsRuntimeContext: () => StackTabsRuntimeContext;

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

@@ -0,0 +1,23 @@
+import { DefineComponent } from 'vue';
+import { ITabBase } from '../../model/TabModel';
+import { StackTabsRuntimeContext } from '../stackTabsContext';
+interface PageComponentFactoryOptions {
+    runtimeContext: StackTabsRuntimeContext;
+    consumeBackParams: (tabId: string, pageId: string) => Record<string, unknown> | null;
+    getComponent: (id: string) => DefineComponent | undefined;
+    setComponent: (id: string, component: DefineComponent) => void;
+    addCache: (cacheName: string) => void;
+    evictMarkedCaches: () => void;
+    clearTabEvictionMarks: () => void;
+    addPageScroller: (pageId: string, ...selectors: string[]) => void;
+    saveScroller: (pageId: string) => void;
+    restoreScroller: (pageId: string) => void;
+    removeScroller: (pageId: string) => void;
+}
+export declare const createPageComponentFactory: (options: PageComponentFactoryOptions) => {
+    resolvePageComponent: (ctx: {
+        cacheName: string;
+        tabInfo: ITabBase;
+    }) => DefineComponent;
+};
+export {};

package/dist/{src/lib/hooks → hooks}/tabPanel/refresh.d.ts

@@ -1,13 +1,16 @@
 import { Ref } from 'vue';
-import { ITabItem } from '../../model/TabModel';
+import { ITabItem, ITabPage } from '../../model/TabModel';
+import { PagePatch } from './tabStore';
 export interface TabPanelRefreshApi {
     refreshTab: (id: string) => void;
     refreshAllTabs: () => void;
 }
 export interface CreateTabPanelRefreshOptions {
-    tabs: Ref<ITabItem[]>;
+    getTabs: () => readonly ITabItem[];
+    getTopPage: (tabId: string) => ITabPage | null;
+    /** 修改页面字段（刷新版本 / 页面 id）并触发 tabs 更新 */
+    updatePage: (tabId: string, pageId: string, patch: PagePatch) => boolean;
     iframeRefreshKeys: Ref<Record<string, number>>;
-    getTab: (id: string) => ITabItem | null;
     createPageId: () => string;
     addCache: (cacheName: string) => void;
     evictPageCache: (cacheName: string) => void;

package/dist/{src/lib/hooks → hooks}/tabPanel/scroll.d.ts

@@ -4,5 +4,7 @@ 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/tabStore.d.ts

@@ -0,0 +1,69 @@
+import { DefineComponent } from 'vue';
+import { ITabItem, ITabPage } from '../../model/TabModel';
+import { StackTabsRuntimeContext } from '../stackTabsContext';
+import { TabPanelEvictionApi } from './evict';
+export interface RemoveTabResult {
+    status: 'not-found' | 'not-closable' | 'removed';
+    removed: ITabItem | null;
+    /** 关闭后应激活的相邻标签；没有可激活标签时为空字符串 */
+    nextActiveId: string;
+}
+/** updatePage 允许修改的字段；页面身份与刷新版本必须通过 store 写入 */
+export interface PagePatch {
+    id?: string;
+    refreshVersion?: number;
+    _backParams?: Record<string, unknown>;
+}
+export interface TabStoreApi extends TabPanelEvictionApi {
+    /** 返回标签列表的只读视图（运行时为同一个响应式数组） */
+    getTabs: () => readonly ITabItem[];
+    getTab: (id: string) => ITabItem | null;
+    getActiveTab: () => ITabItem | null;
+    /** 查找栈顶页面 path 与给定 path 相同的标签 */
+    findTabByTopPagePath: (path: string) => ITabItem | null;
+    hasTab: (id: string) => boolean;
+    canAddTab: () => boolean;
+    getPages: (tabId: string) => readonly ITabPage[];
+    getTopPage: (tabId: string) => ITabPage | null;
+    /** 返回深拷贝的页面栈快照，可直接用于 rollback */
+    getPageSnapshot: (tabId: string) => ITabPage[];
+    addTab: (tab: ITabItem) => void;
+    addTabs: (tabs: readonly ITabItem[]) => void;
+    /** 唯一 active 写入口 */
+    activateTab: (id: string) => ITabItem | null;
+    moveTab: (id: string, targetIndex: number) => boolean;
+    removeTab: (id: string) => RemoveTabResult;
+    removeTabs: (shouldRemove: (tab: ITabItem, index: number) => boolean) => ITabItem[];
+    appendPage: (tabId: string, page: ITabPage) => void;
+    /** 从栈顶弹出若干页，返回被弹出的页面（由调用方决定驱逐/回滚） */
+    popPages: (tabId: string, steps: number) => ITabPage[];
+    /** 用给定页面替换整个栈（内部深拷贝页面） */
+    replacePages: (tabId: string, pages: readonly ITabPage[]) => void;
+    clearPages: (tabId: string) => void;
+    /** 修改页面字段（id / refreshVersion / _backParams），并触发 tabs 更新 */
+    updatePage: (tabId: string, pageId: string, patch: PagePatch) => boolean;
+    /** 取出并清除栈顶页面的 _backParams；pageId 不是当前栈顶时返回 null */
+    consumeBackParams: (tabId: string, pageId: string) => Record<string, unknown> | null;
+    isTabMarkedForEviction: (id: string) => boolean;
+    isCacheMarkedForEviction: (id: string) => boolean;
+    unmarkCacheForEviction: (id: string) => void;
+    clearTabEvictionMarks: () => void;
+    getComponent: (id: string) => DefineComponent | undefined;
+    setComponent: (id: string, component: DefineComponent) => void;
+    deleteComponent: (id: string) => void;
+    snapshotComponents: () => Map<string, DefineComponent>;
+    restoreComponents: (snapshot: Map<string, DefineComponent>) => void;
+    snapshotCaches: () => string[];
+    restoreCaches: (cacheNames: readonly string[]) => void;
+    /** 通知依赖 tabs 的计算属性重新求值（如 activePageRefreshVersion） */
+    touchTabs: () => void;
+    /** 清空 tabs / caches / components / 驱逐标记，供 destroy 使用 */
+    reset: () => void;
+}
+/**
+ * 每个运行时上下文只创建一个 store。
+ *
+ * useTabPanel 会被 StackKeepAlive、StackCacheRenderer、页面内的 useTabRouter 多次调用；
+ * 复用同一实例可避免 eviction 的 Set/数组出现多份互相不同步的状态。
+ */
+export declare const getTabStore: (context: StackTabsRuntimeContext) => TabStoreApi;

package/dist/hooks/useScrollShadow.d.ts

@@ -0,0 +1,20 @@
+import { Ref } from 'vue';
+export interface UseScrollShadowOptions {
+    /** 容器元素的 ref，可以是 Ref<HTMLElement | null> 或 getter 函数 */
+    target: Ref<HTMLElement | null> | (() => HTMLElement | null);
+    /**
+     * 是否监听内容缩放/尺寸变化（默认 true）。
+     * 启用后会用 ResizeObserver 监视目标尺寸，容器或子树尺寸变化都会重新计算阴影边界。
+     */
+    watchResize?: boolean;
+    /**
+     * 到顶/到底的判定阈值（px，默认 5）。
+     * 距离边界 ≤ 阈值视为已贴边（不显示阴影）；距离边界 > 阈值视为可继续滚动（显示阴影）。
+     */
+    edgeThreshold?: number;
+}
+export interface UseScrollShadowReturn {
+    /** 手动同步一次（用于内容变化/resize 后） */
+    sync: () => void;
+}
+export declare const useScrollShadow: (options: UseScrollShadowOptions) => UseScrollShadowReturn;

package/dist/{src/lib/hooks → hooks}/useTabActions.d.ts

@@ -1,4 +1,5 @@
 import { ITabData } from '../model/TabModel';
+import { StackTabsRuntimeContext } from './stackTabsContext';
 /**
  * useTabActions - 标签操作对外 Hook
  *
@@ -12,16 +13,20 @@ import { ITabData } from '../model/TabModel';
  * - activeTab(id, isRoute?) 激活标签
  * - reset() 重置（关闭所有）
  */
-export default function useTabActions(): {
+export default function useTabActions(providedRuntimeContext?: StackTabsRuntimeContext): {
     openTab: (tab: ITabData, renew?: boolean) => Promise<string | undefined>;
     closeTab: (id: string) => string;
     closeAllTabs: () => void;
     refreshTab: (id: string) => void;
     refreshAllTabs: () => void;
     activeTab: (id: string, route?: boolean) => Promise<void | import('vue-router').NavigationFailure | undefined>;
+    moveTab: (id: string, targetIndex: number) => boolean;
     reset: () => void;
     tabs: import('vue').Ref<import('..').ITabItem[], import('..').ITabItem[]>;
     setIFramePath: (path: string) => void;
-    getWrapper: () => Element;
+    getWrapper: (target?: {
+        tabId?: string;
+        pageId?: string;
+    }) => HTMLElement | undefined;
     openInNewWindow: (id: string) => void;
 };