vue-multi-router 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,92 @@
+# vue-multi-router
+
+Vue 3 Multi Router that allows you to have multiple routers in your application.
+
+[![npm downloads](https://img.shields.io/npm/dm/vue-multi-router.svg)](https://www.npmjs.com/package/vue-multi-router)
+[![TypeScript](https://badgen.net/badge/icon/TypeScript?icon=typescript&label)](https://www.typescriptlang.org/)
+[![Vue 3](https://img.shields.io/badge/vue-3.x-brightgreen.svg)](https://vuejs.org/)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/vue-multi-router)](https://bundlephobia.com/package/vue-multi-router)
+[![GitHub issues](https://img.shields.io/github/issues/lviobio/vue-multi-router)](https://github.com/lviobio/vue-multi-router/issues)
+[![GitHub License](https://img.shields.io/github/license/lviobio/vue-multi-router)](https://github.com/lviobio/vue-multi-router)
+![CI](https://github.com/lviobio/vue-multi-router/actions/workflows/ci.yml/badge.svg)
+![Coverage](https://github.com/lviobio/vue-multi-router/actions/workflows/coverage.yml/badge.svg)
+[![codecov](https://codecov.io/gh/lviobio/vue-multi-router/branch/main/graph/badge.svg)](https://codecov.io/gh/lviobio/vue-multi-router)
+[![Live Demo](https://img.shields.io/badge/demo-live-brightgreen)](https://lviobio.github.io/vue-multi-router/)
+
+## Live Demo
+
+🚀 **[Try the interactive playground](https://lviobio.github.io/vue-multi-router)**
+
+## Installation
+
+```bash
+npm install vue-multi-router
+```
+
+## Features
+
+wip
+
+## Basic Usage
+
+wip
+
+## API Reference
+
+wip
+
+## Examples
+
+wip
+
+## Peer Dependencies
+
+- `vue`: ^3.5.0
+- `vue-router`: ^4.0.0
+
+## License
+
+MIT
+
+## Development
+
+### Running Playground Locally
+
+```bash
+# Development mode (hot reload)
+npm run play
+
+# Production preview
+npm run build:playground
+npm run preview:playground
+```
+
+### Building
+
+```bash
+# Build library
+npm run build
+
+# Build playground for deployment
+npm run build:playground
+```
+
+### Testing & Quality
+
+```bash
+# Run all checks
+npm run check
+
+# Type checking
+npm run ts:check
+
+# Linting
+npm run lint
+
+# Formatting
+npm run format
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/index.d.ts

@@ -0,0 +1,356 @@
+import * as vue6 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
+type HistoryLocation = string;
+type HistoryState = Record<string, any>;
+type HistoryBuilder = () => RouterHistory;
+declare enum NavigationType {
+  pop = "pop",
+  push = "push",
+}
+declare enum NavigationDirection {
+  back = "back",
+  forward = "forward",
+  unknown = "",
+}
+interface NavigationInformation {
+  type: NavigationType;
+  direction: NavigationDirection;
+  delta: number;
+}
+interface NavigationCallback {
+  (to: HistoryLocation, from: HistoryLocation, information: NavigationInformation): void;
+}
+interface VirtualStackEntry {
+  location: HistoryLocation;
+  state: HistoryState;
+}
+interface VirtualStack {
+  entries: VirtualStackEntry[];
+  position: number;
+}
+//#endregion
+//#region src/history/storage/types.d.ts
+type MaybePromise<T> = T | Promise<T>;
+interface StoredVirtualStack {
+  entries: Array<{
+    location: string;
+    state: Record<string, any>;
+  }>;
+  position: number;
+}
+interface ContextStorageAdapter {
+  saveStack(contextKey: string, stack: VirtualStack): MaybePromise<void>;
+  restoreStack(contextKey: string): MaybePromise<StoredVirtualStack | null>;
+  clearStack(contextKey: string): MaybePromise<void>;
+  saveActiveContext(contextKey: string): MaybePromise<void>;
+  getActiveContext(): MaybePromise<string | null>;
+  saveActiveHistoryContext(contextKey: string): MaybePromise<void>;
+  getActiveHistoryContext(): MaybePromise<string | null>;
+}
+//#endregion
+//#region src/history/manager.d.ts
+/**
+ * Defines how the browser URL is updated when switching between contexts.
+ *
+ * - `'none'`: URL is not updated when switching contexts. URL changes only on push/replace.
+ *   This gives precise back/forward navigation matching the number of push operations.
+ *
+ * - `'replace'`: URL is updated using history.replace(). This changes the URL immediately
+ *   but overwrites the current history entry's state. May cause issues with forward navigation
+ *   if the previous context had unsaved state.
+ *
+ * - `'push'`: URL is updated using history.push() when the new context's URL differs from current.
+ *   This preserves all history entries but adds extra back steps when switching between
+ *   contexts with different URLs.
+ */
+type ContextSwitchMode = 'none' | 'replace' | 'push';
+interface MultiRouterHistoryManagerOptions {
+  /**
+   * Adapter for persisting context history state.
+   * @default SessionStorageAdapter
+   */
+  storageAdapter?: ContextStorageAdapter;
+  /**
+   * How to update browser URL when switching contexts.
+   * @default 'replace'
+   */
+  contextSwitchMode?: ContextSwitchMode;
+  /**
+   * Callback called when a popstate event requires activating a different context.
+   * This happens when navigating back/forward to a history entry owned by another context.
+   */
+  onContextActivate?: (contextKey: string) => void;
+}
+declare class MultiRouterHistoryManager {
+  private baseHistory;
+  private stacks;
+  private activeHistoryContextKey;
+  private historyContextStack;
+  private baseHistoryCleanup;
+  private contextSwitchMode;
+  private onContextActivate?;
+  constructor(historyBuilder: HistoryBuilder, options?: MultiRouterHistoryManagerOptions);
+  get base(): string;
+  get location(): HistoryLocation;
+  get state(): HistoryState;
+  createContextHistory(contextKey: string, options?: {
+    location?: string;
+    initialLocation?: string;
+    historyEnabled?: boolean;
+  }): MaybePromise<RouterHistory>;
+  private finalizeContextCreation;
+  tryRestoreActiveHistoryContext(contextKey: string): MaybePromise<boolean>;
+  removeContextHistory(contextKey: string): void;
+  setActiveHistoryContext(contextKey: string): void;
+  clearActiveHistoryContext(contextKey: string): void;
+  saveActiveContext(contextKey: string): void;
+  getActiveHistoryContextKey(): string | null;
+  private fallbackToPreviousHistoryContext;
+  private createInitialVirtualStack;
+  private restoreUrlFromVirtualStack;
+  private handlePopState;
+  push(contextKey: string, to: HistoryLocation, data?: HistoryState): void;
+  replace(contextKey: string, to: HistoryLocation, data?: HistoryState): void;
+  go(contextKey: string, delta: number, triggerListeners?: boolean): void;
+  listen(contextKey: string, callback: NavigationCallback): () => void;
+  getContextLocation(contextKey: string): HistoryLocation;
+  getContextState(contextKey: string): HistoryState;
+  createHref(location: HistoryLocation): string;
+  destroy(): void;
+  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/components/MultiRouterContext.vue.d.ts
+declare const _default: typeof __VLS_export$1;
+declare const __VLS_export$1: vue6.DefineComponent<vue6.ExtractPropTypes<{
+  type: {
+    type: StringConstructor;
+    required: true;
+  };
+  name: {
+    type: StringConstructor;
+    required: true;
+  };
+  location: {
+    type: StringConstructor;
+    required: false;
+  };
+  initialLocation: {
+    type: StringConstructor;
+    required: false;
+  };
+  /**
+   * Whether this context should store its navigation history in the browser history.
+   * When false, navigation within this context won't affect browser back/forward.
+   * @default true
+   */
+  historyEnabled: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  /**
+   * Whether this context should be activated by default if no prior active context exists.
+   * Only one context should have this set to true.
+   * @default false
+   */
+  default: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+}>, () => vue6.VNode<vue6.RendererNode, vue6.RendererElement, {
+  [key: string]: any;
+}>, {}, {}, {}, vue6.ComponentOptionsMixin, vue6.ComponentOptionsMixin, {}, string, vue6.PublicProps, Readonly<vue6.ExtractPropTypes<{
+  type: {
+    type: StringConstructor;
+    required: true;
+  };
+  name: {
+    type: StringConstructor;
+    required: true;
+  };
+  location: {
+    type: StringConstructor;
+    required: false;
+  };
+  initialLocation: {
+    type: StringConstructor;
+    required: false;
+  };
+  /**
+   * Whether this context should store its navigation history in the browser history.
+   * When false, navigation within this context won't affect browser back/forward.
+   * @default true
+   */
+  historyEnabled: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  /**
+   * Whether this context should be activated by default if no prior active context exists.
+   * Only one context should have this set to true.
+   * @default false
+   */
+  default: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+}>> & Readonly<{}>, {
+  historyEnabled: boolean;
+  default: boolean;
+}, {}, {}, {}, string, vue6.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<{
+  as: {
+    type: PropType<string | null>;
+    default: null;
+  };
+}>, (() => vue6.VNode<vue6.RendererNode, vue6.RendererElement, {
+  [key: string]: any;
+}>[] | undefined) | (() => vue6.VNode<vue6.RendererNode, vue6.RendererElement, {
+  [key: string]: any;
+}>), {}, {}, {}, vue6.ComponentOptionsMixin, vue6.ComponentOptionsMixin, {}, string, vue6.PublicProps, Readonly<vue6.ExtractPropTypes<{
+  as: {
+    type: PropType<string | null>;
+    default: null;
+  };
+}>> & Readonly<{}>, {
+  as: string | null;
+}, {}, {}, {}, string, vue6.ComponentProvideOptions, true, {}, any>;
+//#endregion
+//#region src/contextManager.d.ts
+type ContextInterface = {
+  type: string;
+  router: Router;
+  history: RouterHistory;
+  initialized: boolean;
+  historyEnabled: boolean;
+};
+interface ActiveContextInterface {
+  key: string;
+  context: ContextInterface;
+}
+type ContextInitListener = (key: string) => void;
+type MakeRouterFn = (contextKey: string, history: RouterHistory) => Router;
+type HistoryManagerOptions = {
+  historyBuilder: HistoryBuilder;
+} & MultiRouterHistoryManagerOptions;
+declare class MultiRouterManagerInstance {
+  private types;
+  private makeRouter;
+  private started;
+  private activeContext;
+  private activeHistoryContext;
+  private registered;
+  private onContextInitListeners;
+  private readonly historyManager;
+  constructor(app: App, types: ContextTypes, historyManagerOptions: HistoryManagerOptions, makeRouter: MakeRouterFn);
+  getHistoryManager(): MultiRouterHistoryManager;
+  getActiveContext(): ActiveContextInterface | undefined;
+  getActiveContextRef(): vue6.ShallowRef<ActiveContextInterface | undefined, ActiveContextInterface | undefined>;
+  getActiveHistoryContext(): ActiveContextInterface | undefined;
+  getActiveHistoryContextRef(): vue6.ShallowRef<ActiveContextInterface | undefined, ActiveContextInterface | undefined>;
+  setActive(key: string, updateHistory: boolean): boolean;
+  clearHistoryContext(key: string): void;
+  markAsStarted(): void;
+  getRouter(key: string): Router;
+  has(key: string): boolean;
+  register(type: string, key: string, options?: {
+    location?: string;
+    initialLocation?: string;
+    historyEnabled?: boolean;
+    default?: boolean;
+  }): MaybePromise<void>;
+  getContextLocation(key: string): string | undefined;
+  getContextHistoryEnabled(key: string): boolean;
+  unregister(key: string): void;
+  initialize(key: string): void;
+  onContextInit(fn: ContextInitListener): void;
+}
+//#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>;
+  activate: (updateHistory?: boolean) => void;
+};
+//#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 };