vue-multi-router 0.1.0 → 0.1.1

package/README.md

@@ -25,19 +25,214 @@ npm install vue-multi-router
 
 ## Features
 
-wip
+- **Multiple Independent Routers** - Run multiple Vue Router instances simultaneously in a single app
+- **Context-Based Navigation** - Each routing context maintains its own navigation history
+- **Browser History Integration** - Back/forward buttons work across contexts with proper URL updates
+- **Session Persistence** - Context states persist across page reloads via SessionStorage or other implementations
+- **TypeScript Support** - Full type definitions included
+- **Composable API** - Easy-to-use composables for accessing router state
 
 ## Basic Usage
 
-wip
+### 1. Create Multi Router
+
+```typescript
+// router.ts
+import { createMultiRouter } from 'vue-multi-router'
+import { createWebHistory } from 'vue-router'
+
+export const multiRouter = createMultiRouter({
+  history: () => createWebHistory(),
+  routes: [
+    {
+      path: '/',
+      component: () => import('./views/Layout.vue'),
+      children: [
+        { path: 'home', component: () => import('./views/Home.vue') },
+        { path: 'about', component: () => import('./views/About.vue') },
+      ],
+    },
+  ],
+})
+```
+
+### 2. Install Plugin
+
+```typescript
+// main.ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import { multiRouter } from './router'
+
+const app = createApp(App)
+app.use(multiRouter)
+app.mount('#app')
+```
+
+### 3. Define Contexts
+
+```vue
+<!-- App.vue -->
+<template>
+  <MultiRouterContext type="main" name="main" default>
+    <RouterView />
+  </MultiRouterContext>
+</template>
+
+<script setup>
+import { MultiRouterContext } from 'vue-multi-router'
+</script>
+```
+
+`MultiRouterContext` acts as an activator by default — clicking anywhere inside it activates the context. No extra wrapper needed.
+
+### 4. Create Additional Contexts
+
+```vue
+<!-- Panels.vue -->
+<template>
+  <div v-for="panel in panels" :key="panel.id">
+    <MultiRouterContext
+      type="panel"
+      :name="`panel-${panel.id}`"
+      initial-location="/home"
+    >
+      <RouterView />
+    </MultiRouterContext>
+  </div>
+</template>
+```
 
 ## API Reference
 
-wip
+### `createMultiRouter(options)`
+
+Creates a multi-router instance.
+
+**Options:**
+- `history: () => RouterHistory` - Factory function returning a Vue Router history instance
+- `routes: RouteRecordRaw[]` - Route definitions (same as Vue Router)
+- `historyOptions?: MultiRouterHistoryManagerOptions` - History management options
+
+### Route Meta Options
+
+**`multiRouterRoot: boolean`**
+
+Marks a route as the root for context rendering. When a context navigates to a nested route, `RouterView` inside the context will start rendering from the route marked with `multiRouterRoot: true`, skipping parent routes.
+
+```typescript
+const routes = [
+  {
+    path: '/dashboard',
+    component: DashboardLayout,
+    children: [
+      {
+        path: 'panels',
+        component: PanelsContainer,
+        children: [
+          {
+            path: 'content',
+            component: PanelContent,
+            meta: { multiRouterRoot: true }, // Context renders from here
+          },
+        ],
+      },
+    ],
+  },
+]
+```
+
+This is useful when contexts are nested inside shared layouts but should render independently from their root component.
+
+### `<MultiRouterContext>`
+
+Component that defines a routing context boundary. By default, it also acts as an activator — clicking inside the context activates it.
+
+**Props:**
+- `type: string` - Context type identifier (for debugging/organization)
+- `name: string` - Unique context identifier
+- `location?: string` - Force specific location (overrides storage)
+- `initial-location?: string` - Initial location for new contexts
+- `history-enabled?: boolean` - Whether to track in browser history (default: `true`)
+- `default?: boolean` - Activate by default if no saved context exists
+- `activator?: boolean` - Whether to activate context on mousedown (default: `true`). Set to `false` to opt out of built-in activation behavior
+- `prevent-class?: string` - CSS class that prevents activation on click, useful if you want to prevent activation on click of a button that destroys the context
+
+To disable the built-in activator:
+
+```vue
+<MultiRouterContext type="panel" name="panel-1" :activator="false">
+  <!-- manage activation manually -->
+</MultiRouterContext>
+```
+
+### `<MultiRouterContextActivator>`
+
+Standalone wrapper component that activates context on user interaction. Useful for advanced cases where you need fine-grained control over which element triggers activation, separate from the `MultiRouterContext` boundary.
+
+**Props:**
+- `prevent-class?: string` - CSS class that prevents activation on click
+- `as?: string` - HTML element to render as wrapper (default: fragment/div)
+
+### `useMultiRouter()`
+
+Composable for accessing multi-router outside a context.
+
+**Returns:**
+- `activeContextKey: ComputedRef<string | undefined>` - Currently active context
+- `activeHistoryContextKey: ComputedRef<string | undefined>` - Context controlling browser URL
+- `setActive(contextKey: string, updateHistory?: boolean): void` - Activate a context
+- `hasContext(contextKey: string): boolean` - Check if context exists
+
+### `useMultiRouterContext()`
+
+Composable for use inside a `MultiRouterContext`.
+
+**Returns:**
+- `router: ComputedRef<Router>` - Vue Router instance for this context
+- `route: ComputedRef<RouteLocationNormalized>` - Current route
+- `isActive: ComputedRef<boolean>` - Whether this context is active
+- `isHistoryActive: ComputedRef<boolean>` - Whether this context controls browser URL
+- `activate(updateHistory?: boolean): void` - Activate this context
+- `contextKey: string` - This context's key
 
 ## Examples
 
-wip
+### Cards with Query Parameters
+
+```vue
+<template>
+  <div v-for="card in cards" :key="card.id">
+    <MultiRouterContext
+      type="card"
+      :name="`card-${card.id}`"
+      initial-location="/card/content"
+      :history-enabled="false"
+    >
+      <CardContent @close="removeCard(card.id)" />
+    </MultiRouterContext>
+  </div>
+</template>
+```
+
+### Accessing Route in Context
+
+```vue
+<script setup>
+import { useRouter, useRoute } from 'vue-router'
+
+const router = useRouter()
+const route = useRoute()
+
+// Navigate within this context
+function goToPage(path) {
+  router.push(path)
+}
+
+// Access query params
+const searchQuery = computed(() => route.query.q)
+</script>
+```
 
 ## Peer Dependencies
 

package/dist/index.d.ts

@@ -1,6 +1,5 @@
-import * as vue6 from "vue";
+import * as vue0 from "vue";
 import { App, InjectionKey, PropType } from "vue";
-import * as vue_router0 from "vue-router";
 import { Router, RouterHistory, RouterOptions } from "vue-router";
 
 //#region src/history/types.d.ts
@@ -48,8 +47,26 @@ interface ContextStorageAdapter {
   clearStack(contextKey: string): MaybePromise<void>;
   saveActiveContext(contextKey: string): MaybePromise<void>;
   getActiveContext(): MaybePromise<string | null>;
+  clearActiveContext(): MaybePromise<void>;
   saveActiveHistoryContext(contextKey: string): MaybePromise<void>;
   getActiveHistoryContext(): MaybePromise<string | null>;
+  clearActiveHistoryContext(): MaybePromise<void>;
+  /**
+   * Save the stack of previously active contexts (for fallback when closing a context)
+   */
+  saveContextStack(stack: string[]): MaybePromise<void>;
+  /**
+   * Get the stack of previously active contexts
+   */
+  getContextStack(): MaybePromise<string[]>;
+  /**
+   * Save the stack of previously active history contexts (for fallback when closing a context)
+   */
+  saveHistoryContextStack(stack: string[]): MaybePromise<void>;
+  /**
+   * Get the stack of previously active history contexts
+   */
+  getHistoryContextStack(): MaybePromise<string[]>;
 }
 //#endregion
 //#region src/history/manager.d.ts
@@ -90,10 +107,12 @@ declare class MultiRouterHistoryManager {
   private stacks;
   private activeHistoryContextKey;
   private historyContextStack;
+  private contextStack;
   private baseHistoryCleanup;
   private contextSwitchMode;
   private onContextActivate?;
   constructor(historyBuilder: HistoryBuilder, options?: MultiRouterHistoryManagerOptions);
+  private restoreContextStacks;
   get base(): string;
   get location(): HistoryLocation;
   get state(): HistoryState;
@@ -108,6 +127,24 @@ declare class MultiRouterHistoryManager {
   setActiveHistoryContext(contextKey: string): void;
   clearActiveHistoryContext(contextKey: string): void;
   saveActiveContext(contextKey: string): void;
+  /**
+   * Push the current active context to the context stack before switching to a new one.
+   * This allows fallback to the previous context when the current one is removed.
+   */
+  pushToContextStack(contextKey: string): void;
+  /**
+   * Get the previous context from the stack (for fallback when current context is removed).
+   * Returns null if no previous context exists.
+   */
+  popFromContextStack(): string | null;
+  /**
+   * Remove a context from the context stack (when the context is unregistered).
+   */
+  removeFromContextStack(contextKey: string): void;
+  /**
+   * Clear the active context from storage (when no contexts are left).
+   */
+  clearActiveContext(): void;
   getActiveHistoryContextKey(): string | null;
   private fallbackToPreviousHistoryContext;
   private createInitialVirtualStack;
@@ -124,71 +161,23 @@ declare class MultiRouterHistoryManager {
   getLastActiveContextKey(): MaybePromise<string | null>;
 }
 //#endregion
-//#region src/types.d.ts
-type Wip = true;
-interface ContextTypeOptions {
-  canUseAsHistoryContext: boolean;
-  single: boolean;
-}
-type ContextTypes = Record<string, ContextTypeOptions>;
-//#endregion
 //#region src/multi-router.d.ts
 type MultiRouterInterface = {
   getByContextName: (name: string) => Router;
   install: (app: App) => void;
 };
-declare const contextTemplateWindows: {
-  window: {
-    canUseAsHistoryContext: true;
-    single: false;
-  };
-};
-declare const contextTemplateTabs: {
-  tab: {
-    canUseAsHistoryContext: true;
-    single: false;
-  };
-};
-declare const contextTemplateMainWithWindows: {
-  window: {
-    canUseAsHistoryContext: true;
-    single: false;
-  };
-  main: {
-    canUseAsHistoryContext: true;
-    single: true;
-  };
-};
-declare const contextTemplateDesktopWithWindows: {
-  window: {
-    canUseAsHistoryContext: true;
-    single: false;
-  };
-  desktop: {
-    canUseAsHistoryContext: false;
-    single: true;
-  };
-};
-declare const contextTemplateTabsWithWindows: {
-  window: {
-    canUseAsHistoryContext: true;
-    single: false;
-  };
-  tab: {
-    canUseAsHistoryContext: true;
-    single: false;
-  };
-};
 type CustomRouterOptions = Omit<RouterOptions, 'history'> & {
   history: () => RouterHistory;
   historyOptions?: MultiRouterHistoryManagerOptions;
-  types: ContextTypes;
 };
 declare function createMultiRouter(options: CustomRouterOptions): MultiRouterInterface;
 //#endregion
+//#region src/hooks.d.ts
+declare function onMultiRouterContextActivate(callback: (name: string) => void): void;
+//#endregion
 //#region src/components/MultiRouterContext.vue.d.ts
 declare const _default: typeof __VLS_export$1;
-declare const __VLS_export$1: vue6.DefineComponent<vue6.ExtractPropTypes<{
+declare const __VLS_export$1: vue0.DefineComponent<vue0.ExtractPropTypes<{
   type: {
     type: StringConstructor;
     required: true;
@@ -223,9 +212,27 @@ declare const __VLS_export$1: vue6.DefineComponent<vue6.ExtractPropTypes<{
     type: BooleanConstructor;
     default: boolean;
   };
-}>, () => vue6.VNode<vue6.RendererNode, vue6.RendererElement, {
+  /**
+   * Whether this context should act as an activator, activating the context on mousedown.
+   * Set false to opt out of built-in activation behavior.
+   * @default true
+   */
+  activator: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  /**
+   * CSS class that prevents activation when the mousedown target matches.
+   * Only used when activator is true.
+   * @default null
+   */
+  preventClass: {
+    type: PropType<string | null>;
+    default: null;
+  };
+}>, () => vue0.VNode<vue0.RendererNode, vue0.RendererElement, {
   [key: string]: any;
-}>, {}, {}, {}, vue6.ComponentOptionsMixin, vue6.ComponentOptionsMixin, {}, string, vue6.PublicProps, Readonly<vue6.ExtractPropTypes<{
+}>, {}, {}, {}, vue0.ComponentOptionsMixin, vue0.ComponentOptionsMixin, {}, string, vue0.PublicProps, Readonly<vue0.ExtractPropTypes<{
   type: {
     type: StringConstructor;
     required: true;
@@ -260,30 +267,61 @@ declare const __VLS_export$1: vue6.DefineComponent<vue6.ExtractPropTypes<{
     type: BooleanConstructor;
     default: boolean;
   };
+  /**
+   * Whether this context should act as an activator, activating the context on mousedown.
+   * Set false to opt out of built-in activation behavior.
+   * @default true
+   */
+  activator: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  /**
+   * CSS class that prevents activation when the mousedown target matches.
+   * Only used when activator is true.
+   * @default null
+   */
+  preventClass: {
+    type: PropType<string | null>;
+    default: null;
+  };
 }>> & Readonly<{}>, {
   historyEnabled: boolean;
   default: boolean;
-}, {}, {}, {}, string, vue6.ComponentProvideOptions, true, {}, any>;
+  activator: boolean;
+  preventClass: string | null;
+}, {}, {}, {}, string, vue0.ComponentProvideOptions, true, {}, any>;
 //#endregion
 //#region src/components/MultiRouterContextActivator.vue.d.ts
 declare const _default$1: typeof __VLS_export;
-declare const __VLS_export: vue6.DefineComponent<vue6.ExtractPropTypes<{
+declare const __VLS_export: vue0.DefineComponent<vue0.ExtractPropTypes<{
   as: {
     type: PropType<string | null>;
     default: null;
   };
-}>, (() => vue6.VNode<vue6.RendererNode, vue6.RendererElement, {
+  preventClass: {
+    type: PropType<string | null>;
+    default: null;
+    required: false;
+  };
+}>, (() => vue0.VNode<vue0.RendererNode, vue0.RendererElement, {
   [key: string]: any;
-}>[] | undefined) | (() => vue6.VNode<vue6.RendererNode, vue6.RendererElement, {
+}>[] | undefined) | (() => vue0.VNode<vue0.RendererNode, vue0.RendererElement, {
   [key: string]: any;
-}>), {}, {}, {}, vue6.ComponentOptionsMixin, vue6.ComponentOptionsMixin, {}, string, vue6.PublicProps, Readonly<vue6.ExtractPropTypes<{
+}>), {}, {}, {}, vue0.ComponentOptionsMixin, vue0.ComponentOptionsMixin, {}, string, vue0.PublicProps, Readonly<vue0.ExtractPropTypes<{
   as: {
     type: PropType<string | null>;
     default: null;
   };
+  preventClass: {
+    type: PropType<string | null>;
+    default: null;
+    required: false;
+  };
 }>> & Readonly<{}>, {
+  preventClass: string | null;
   as: string | null;
-}, {}, {}, {}, string, vue6.ComponentProvideOptions, true, {}, any>;
+}, {}, {}, {}, string, vue0.ComponentProvideOptions, true, {}, any>;
 //#endregion
 //#region src/contextManager.d.ts
 type ContextInterface = {
@@ -303,7 +341,6 @@ type HistoryManagerOptions = {
   historyBuilder: HistoryBuilder;
 } & MultiRouterHistoryManagerOptions;
 declare class MultiRouterManagerInstance {
-  private types;
   private makeRouter;
   private started;
   private activeContext;
@@ -311,12 +348,12 @@ declare class MultiRouterManagerInstance {
   private registered;
   private onContextInitListeners;
   private readonly historyManager;
-  constructor(app: App, types: ContextTypes, historyManagerOptions: HistoryManagerOptions, makeRouter: MakeRouterFn);
+  constructor(app: App, historyManagerOptions: HistoryManagerOptions, makeRouter: MakeRouterFn);
   getHistoryManager(): MultiRouterHistoryManager;
   getActiveContext(): ActiveContextInterface | undefined;
-  getActiveContextRef(): vue6.ShallowRef<ActiveContextInterface | undefined, ActiveContextInterface | undefined>;
+  getActiveContextRef(): vue0.ShallowRef<ActiveContextInterface | undefined, ActiveContextInterface | undefined>;
   getActiveHistoryContext(): ActiveContextInterface | undefined;
-  getActiveHistoryContextRef(): vue6.ShallowRef<ActiveContextInterface | undefined, ActiveContextInterface | undefined>;
+  getActiveHistoryContextRef(): vue0.ShallowRef<ActiveContextInterface | undefined, ActiveContextInterface | undefined>;
   setActive(key: string, updateHistory: boolean): boolean;
   clearHistoryContext(key: string): void;
   markAsStarted(): void;
@@ -331,26 +368,43 @@ declare class MultiRouterManagerInstance {
   getContextLocation(key: string): string | undefined;
   getContextHistoryEnabled(key: string): boolean;
   unregister(key: string): void;
+  private activateFromStackOrFallback;
+  private fallbackToPreviousContext;
   initialize(key: string): void;
   onContextInit(fn: ContextInitListener): void;
 }
 //#endregion
+//#region src/composables/useMultiRouter.d.ts
+/**
+ * Composable for accessing the multi-router manager outside a context.
+ * Use this when you need to control contexts from a parent component.
+ *
+ * For usage inside a context, use `useMultiRouterContext()` instead.
+ */
+declare function useMultiRouter(): {
+  manager: MultiRouterManagerInstance;
+  activeContextKey: vue0.ComputedRef<string | undefined>;
+  activeHistoryContextKey: vue0.ComputedRef<string | undefined>;
+  setActive: (contextKey: string, updateHistory?: boolean) => void;
+  hasContext: (contextKey: string) => boolean;
+};
+//#endregion
 //#region src/composables/useMultiRouterContext.d.ts
 declare function useMultiRouterContext(): {
   manager: MultiRouterManagerInstance;
   contextKey: string;
-  router: vue6.ComputedRef<Router>;
-  route: vue6.ComputedRef<vue_router0.RouteLocationNormalizedLoadedGeneric>;
-  isActive: vue6.ComputedRef<boolean>;
-  isHistoryActive: vue6.ComputedRef<boolean>;
-  activeContextKey: vue6.ComputedRef<string | undefined>;
-  activeHistoryContextKey: vue6.ComputedRef<string | undefined>;
-  historyEnabled: vue6.ComputedRef<boolean>;
+  isActive: vue0.ComputedRef<boolean>;
+  isHistoryActive: vue0.ComputedRef<boolean>;
+  activeContextKey: vue0.ComputedRef<string | undefined>;
+  activeHistoryContextKey: vue0.ComputedRef<string | undefined>;
+  historyEnabled: vue0.ComputedRef<boolean>;
   activate: (updateHistory?: boolean) => void;
+  setActive: (contextKey: string, updateHistory?: boolean) => void;
+  hasContext: (contextKey: string) => boolean;
 };
 //#endregion
 //#region src/injectionSymbols.d.ts
 declare const multiRouterContextManagerKey: InjectionKey<MultiRouterManagerInstance>;
 declare const multiRouterContextKey: InjectionKey<string>;
 //#endregion
-export { type ContextSwitchMode, ContextTypeOptions, ContextTypes, type HistoryBuilder, type HistoryLocation, type HistoryState, _default as MultiRouterContext, _default$1 as MultiRouterContextActivator, type MultiRouterHistoryManagerOptions, type NavigationCallback, type NavigationInformation, type VirtualStack, Wip, contextTemplateDesktopWithWindows, contextTemplateMainWithWindows, contextTemplateTabs, contextTemplateTabsWithWindows, contextTemplateWindows, createMultiRouter, multiRouterContextKey, multiRouterContextManagerKey, useMultiRouterContext };
+export { type ContextSwitchMode, type HistoryBuilder, type HistoryLocation, type HistoryState, _default as MultiRouterContext, _default$1 as MultiRouterContextActivator, type MultiRouterHistoryManagerOptions, type NavigationCallback, type NavigationInformation, type VirtualStack, createMultiRouter, multiRouterContextKey, multiRouterContextManagerKey, onMultiRouterContextActivate, useMultiRouter, useMultiRouterContext };