@virou/core 0.1.0 → 1.0.0

package/README.md

@@ -0,0 +1,335 @@
+# 🧭 Virou
+
+<p>
+  <a href="https://www.npmjs.com/package/@virou/core"><img src="https://img.shields.io/npm/v/@virou/core.svg?style=flat&colorA=18181B&colorB=39737d" alt="Version"></a>
+  <a href="https://www.npmjs.com/package/@virou/core"><img src="https://img.shields.io/npm/dm/@virou/core.svg?style=flat&colorA=18181B&colorB=39737d" alt="Downloads"></a>
+  <a href="https://bundlephobia.com/package/@virou/core"><img src="https://img.shields.io/bundlephobia/min/@virou/core?style=flat&colorA=18181B&colorB=39737d" alt="Bundle Size"></a>
+  <a href="https://github.com/tankosinn/virou/tree/main/LICENSE"><img src="https://img.shields.io/github/license/tankosinn/virou.svg?style=flat&colorA=18181B&colorB=39737d" alt="License"></a>
+</p>
+
+Virou is a high-performance, lightweight virtual router for Vue with dynamic routing capabilities.
+
+> Perfect for modals, wizards, embeddable widgets, or any scenario requiring routing without altering the browser's URL or history.
+
+## ✨ Features
+
+- 🪄 **Dynamic Virtual Routing**: Navigate without altering the browser's URL or history
+- 🍂 **Multiple Router Instances**: Manage independent routing contexts within the same app
+- 🪆 **Nested Routing**: Seamlessly handle complex, nested routes
+- 🦾 **Type-Safe**: Written in [TypeScript](https://www.typescriptlang.org/)
+- ⚡ **SSR-Friendly**: Compatible with server-side rendering
+
+## 🐣 Usage
+```vue
+<script setup lang="ts">
+import { useVRouter } from '@virou/core'
+
+// Define your routes
+const routes = [
+  {
+    path: '/',
+    component: () => import('./views/Home.vue'),
+  },
+  {
+    path: '/about',
+    component: () => import('./views/About.vue'),
+  },
+]
+
+// Create a virtual router instance
+const { router, route } = useVRouter(routes)
+</script>
+
+<template>
+  <!-- Renders the current route's component -->
+  <VRouterView />
+</template>
+```
+
+## 📦 Installation
+
+Install Virou with your package manager:
+
+```bash
+pnpm add @virou/core
+```
+
+Register the `virou` plugin in your Vue app:
+
+```typescript
+import { virou } from '@virou/core'
+import { createApp } from 'vue'
+import App from './App.vue'
+
+createApp(App)
+  .use(virou)
+  .mount('#app')
+```
+
+### 🧩 Using with Nuxt
+
+Install Virou Nuxt module with your package manager:
+
+```bash
+pnpm add @virou/nuxt
+```
+
+Add the module to your Nuxt configuration:
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: [
+    '@virou/nuxt',
+  ],
+})
+```
+
+## 🧱 Essentials
+
+### 🌿 Routes
+
+Declare your routes as an array of objects with required `path` and `component`, and optional `meta` and `children` properties.
+
+```typescript
+const routes: VRouterRaw[] = [
+  {
+    path: '/', // static path
+    component: Home,
+  },
+  {
+    path: '/user/:id', // dynamic path with parameter
+    component: () => import('./views/User.vue'),
+    meta: {
+      foo: 'bar',
+    }
+  },
+  {
+    path: '/**:notFound', // Named wildcard path
+    component: defineAsyncComponent(() => import('./views/NotFound.vue')),
+  }
+]
+```
+
+**Props**:
+- `path`: the URL pattern to match. Supports:
+  - Static ("/about") for exact matches
+  - Dynamic ("/user/:id") for named parameters
+  - Wildcard ("/**") for catch-all segments
+  - Named wildcard ("/**:notFound") for catch-all with a name
+- `component`: the Vue component to render when this route matches. Can be synchronous or an async loader.
+- `meta`: metadata for the route.
+- `children`: an array of child routes.
+
+> Virou uses [rou3](https://github.com/h3js/rou3) under the hood for create router context and route matching.
+
+### 🪆 Nested Routes
+
+To define nested routes, add a children array to a route record. Child path values are relative to their parent (leading `/` is ignored).
+
+```typescript
+const routes: VRouterRaw[] = [
+  // ...
+  {
+    path: '/user/:id',
+    component: User,
+    children: [
+      {
+        path: '', // /user/:id  -> default child route
+        component: UserProfile,
+      },
+      {
+        path: '/settings', // /user/:id/settings
+        component: UserSettings,
+        children: [
+          {
+            path: '/', // /user/:id/settings -> deep default child route
+            component: UserSettingsGeneral,
+          },
+          {
+            path: '/notifications', // /user/:id/settings/notifications
+            component: UserSettingsNotifications,
+          },
+        ],
+      },
+    ]
+  },
+  // ...
+]
+```
+
+### 🌳 Router
+
+Create (or access) a virtual router instance with `useVRouter` composable.
+
+```typescript
+const { router, route } = useVRouter('my-wizard', routes)
+```
+
+> `useVRouter` must be called inside `setup()`.
+
+**Params:**
+- `key`: a unique key for the router instance. If you do not provide a key, Virou will generate one via `useId()`.
+- `routes`: an array of route objects.
+- `options`:
+  - `initialPath`: the path to render on initialization (defaults to `/`).
+
+**Returns:**
+- `route`: a Vue shallow ref that contains the current route object.
+  ```typescript
+  export interface VRoute {
+    fullPath: string
+    path: string
+    search: string
+    hash: string
+    meta?: Record<PropertyKey, unknown>
+    params?: Record<string, string>
+    _renderList: Component[] | null
+  }
+  ```
+- `router`:
+  - `replace(path: string): void`: navigate to a new path.
+  - `addRoute(route: VRouteRaw): void`: add a route at runtime.
+
+#### 🍃 Multiple Router Instances
+
+Virou allows you to create multiple independent router instances within the same app.
+
+```vue
+<script setup lang="ts">
+// Settings modal router
+useVRouter('settings-modal', [
+  {
+    path: '/profile',
+    component: UserProfile,
+  },
+  {
+    path: '/preferences',
+    component: UserPreferences,
+  },
+  // ...
+], { initialPath: '/profile' })
+
+// Onboarding wizard router
+useVRouter('onboarding-wizard', [
+  {
+    path: '/profile',
+    component: OnboardingProfile,
+  },
+  {
+    path: '/teamspace',
+    component: OnboardingTeamspace,
+  },
+  // ...
+], { initialPath: '/profile' })
+</script>
+
+<template>
+  <SettingsModal>
+    <VRouterView router-key="settings-modal" />
+  </SettingsModal>
+
+  <Wizard>
+    <VRouterView router-key="onboarding-wizard" />
+  </Wizard>
+</template>
+```
+
+## 📺 Rendering
+
+`<VRouterView>` mounts the matched component at its current nesting depth.
+
+```vue
+<template>
+  <VRouterView router-key="my-router">
+    :keep-alive="true"     <!-- preserve component state -->
+    :view-key="(route, key) => `${key}|${route.fullPath}`" <!-- custom vnode key -->
+    >
+    <!-- default slot receives { Component, route } -->
+    <template #default="{ Component, route }">
+      <Transition name="fade" mode="out-in">
+        <component :is="Component" v-bind="route.params" />
+      </Transition>
+    </template>
+
+    <!-- fallback slot shown while async loader resolves -->
+    <template #fallback>
+      <div class="spinner">
+        Loading...
+      </div>
+    </template>
+  </VRouterView>
+</template>
+```
+
+**Props:**
+- `routerKey`: key of the router instance to render. If not provided, uses the nearest router instance.
+- `keepAlive`: wraps the rendered component in `<KeepAlive>` when set to true, preserving its state across navigations.
+- `viewKey`: accepts either a string or a function `(route, key) => string` to compute the vnode key for the rendered component.
+
+**Slots:**
+- `default`: slot receives `{ Component, route }` so you can wrap or decorate the active component.
+- `fallback`: receives `{ route }` and is displayed inside `<Suspense>` while an async component is resolving.
+
+> Virou wraps components in `<Suspense>` by default. To combine `<Suspense>` with other components, see the [Vue docs](https://vuejs.org/guide/built-ins/suspense#combining-with-other-components).
+
+## 🛠️ Advanced
+
+### 🌐 Global Routers
+
+By default, routers created with `useVRouter(key, routes)` are disposable—they unregister themselves automatically once no components reference them.
+
+To keep a router alive for your app’s entire lifecycle, register it as a global router.
+
+#### Plugin-Registered Globals
+
+Defined routers in the `virou` plugin options are registered as global routers:
+
+```ts
+createApp(App)
+  .use(virou, {
+    routers: {
+      'embedded-widget-app': {
+        routes: [
+          { path: '/chat', component: () => import('./views/Chat.vue') },
+          { path: '/settings', component: () => import('./views/Settings.vue') },
+        ],
+        options: { initialPath: '/chat' }
+      },
+      // add more global routers here...
+    }
+  })
+  .mount('#app')
+```
+
+Later:
+
+```ts
+const { router, route } = useVRouter('embedded-widget-app')
+```
+
+#### Runtime-Registered Globals
+
+You may also mark a router as global at runtime by passing the `_isGlobal` option:
+
+```ts
+useVRouter(routes, { _isGlobal: true })
+```
+
+That router will stay registered even after components that use it unmount.
+
+### 🧪 Create Standalone Virtual Router
+
+You can create a standalone virtual router with `createVRouter`:
+
+```ts
+export function useCustomRouter() {
+  const { router, route } = createVRouter(routes)
+
+  // Custom logic here...
+}
+```
+
+## 📝 License
+
+[MIT License](https://github.com/tankosinn/virou/blob/main/LICENSE)

package/dist/index.d.mts

@@ -1,99 +1,107 @@
-import * as vue from 'vue';
-import { Component, AsyncComponentLoader, ComputedRef } from 'vue';
 import { RouterContext } from 'rou3';
+import * as vue from 'vue';
+import { Component, DefineComponent, Ref, ShallowRef, PropType, SlotsType, VNodeChild, Plugin } from 'vue';
 
-declare const VRouterView: vue.DefineComponent<vue.ExtractPropTypes<{
-    routerKey: {
-        type: StringConstructor;
-        default: undefined;
-    };
-    viewKey: {
-        type: StringConstructor;
-        default: undefined;
-    };
-    keepalive: {
-        type: BooleanConstructor;
-        default: boolean;
-    };
-}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
-    [key: string]: any;
-}> | null, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
-    routerKey: {
-        type: StringConstructor;
-        default: undefined;
-    };
-    viewKey: {
-        type: StringConstructor;
-        default: undefined;
-    };
-    keepalive: {
-        type: BooleanConstructor;
-        default: boolean;
-    };
-}>> & Readonly<{}>, {
-    routerKey: string;
-    viewKey: string;
-    keepalive: boolean;
-}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
-
-type VRouteTreeNode = [key: string, children?: VRouteTreeNode[]];
-type VRouteViews = Record<string, Component[]>;
-type VRouteKeys = Record<string, Array<string | null>>;
-type VRouteRenderView = [key: string, component: Component];
-interface VRouteRecordRaw {
-    key?: string;
+type Lazy<T> = () => Promise<T>;
+type VRouteComponent = Component | DefineComponent;
+type VRouteLazyComponent = Lazy<VRouteComponent>;
+type VRouteRenderComponent = VRouteComponent | VRouteLazyComponent;
+type VRouteMeta = Record<PropertyKey, unknown>;
+interface VRouteRaw {
     path: string;
-    component: AsyncComponentLoader<Component>;
-    meta?: Record<string, any>;
-    children?: VRouteRecordRaw[];
+    component: VRouteRenderComponent;
+    meta?: VRouteMeta;
+    children?: VRouteRaw[];
 }
+type VRouteId = Readonly<[path: string, depth: number]>;
 interface VRouteMatchedData {
-    key?: string;
+    id: VRouteId;
+    meta?: VRouteMeta;
+}
+interface VRouteNormalized extends Omit<VRouteRaw, 'path' | 'children'> {
+    parentId?: VRouteId;
+}
+type VRoutesMap = Map<VRouteId, VRouteNormalized>;
+interface VRoute {
     fullPath: string;
-    meta?: Record<string, any>;
+    meta?: VRouteMeta;
+    params?: Record<string, string>;
+    path: string;
+    search: string;
+    hash: string;
+    _renderList: Component[] | null;
 }
-interface VRouterInstance {
+interface VRouterData {
     context: RouterContext<VRouteMatchedData>;
-    routeTree: VRouteTreeNode[];
-    views: VRouteViews;
-    keys: VRouteKeys;
+    routes: VRoutesMap;
+    activePath: Ref<string>;
+    route: ShallowRef<VRoute>;
+    _isGlobal: boolean;
+    _deps: number;
+    _dispose: () => void;
 }
 interface VRouterOptions {
-    initialPath: string;
+    initialPath?: string;
+    _isGlobal?: boolean;
 }
 interface VRouter {
-    route: ComputedRef<{
-        fullPath: string;
-        data?: VRouteMatchedData;
-        params?: Record<string, string>;
-        path: string;
-        search: string;
-        hash: string;
-        activeRouteTree?: string[];
-        renderList?: VRouteRenderView[];
-    }>;
+    route: VRouterData['route'];
     router: {
-        addRoute: (route: VRouteRecordRaw) => void;
+        addRoute: (route: VRouteRaw) => void;
         replace: (path: string) => void;
-        _key: string;
         _depthKey: symbol;
     };
 }
+interface VirouPluginOptions {
+    routers?: Record<string, {
+        routes: VRouteRaw[];
+        options?: Omit<VRouterOptions, '_isGlobal'>;
+    }>;
+}
+
+declare module 'vue' {
+  interface ComponentCustomProperties {
+    $virou: Map<string, VRouterData>
+  }
+}
+
+declare const VRouterView: vue.DefineComponent<vue.ExtractPropTypes<{
+    routerKey: StringConstructor;
+    keepAlive: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    viewKey: {
+        type: PropType<string | ((route: VRoute, key: string) => string)>;
+    };
+}>, () => string | number | boolean | vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}> | vue.VNodeArrayChildren | null, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    routerKey: StringConstructor;
+    keepAlive: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    viewKey: {
+        type: PropType<string | ((route: VRoute, key: string) => string)>;
+    };
+}>> & Readonly<{}>, {
+    keepAlive: boolean;
+}, SlotsType<{
+    default: (payload: {
+        Component: VNodeChild;
+        route: VRoute;
+    }) => VNodeChild;
+    fallback: (payload: {
+        route: VRoute;
+    }) => VNodeChild;
+}>, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+
+declare const virou: Plugin<[VirouPluginOptions?]>;
 
 declare const virouSymbol: unique symbol;
-declare function createVRouter(key: string, routes: VRouteRecordRaw[], options?: VRouterOptions): void;
-/**
- * Creates or retrieves a virtual router
- *
- * @param key - a unique identifier for the router
- * @param routes - a list of routes to add to the router
- * @param options - configuration options for the router
- *
- * @returns an object containing:
- *   - `route`: reactive data for the current route (e.g., path, fullPath, query, etc.)
- *   - `router`: utilities to manage the router (e.g., `addRoute`, `replace`)
- */
-declare function useVRouter(key?: string, routes?: VRouteRecordRaw[], options?: VRouterOptions): VRouter;
-declare function useVRouter(routes?: VRouteRecordRaw[], options?: VRouterOptions): VRouter;
+declare function createVRouter(routes: VRouteRaw[], options?: VRouterOptions): VRouterData;
+declare function useVRouter(routes?: VRouteRaw[], options?: VRouterOptions): VRouter;
+declare function useVRouter(key?: string, routes?: VRouteRaw[], options?: VRouterOptions): VRouter;
 
-export { type VRouteKeys, type VRouteMatchedData, type VRouteRecordRaw, type VRouteRenderView, type VRouteTreeNode, type VRouteViews, type VRouter, type VRouterInstance, type VRouterOptions, VRouterView, createVRouter, useVRouter, virouSymbol };
+export { type VRoute, type VRouteComponent, type VRouteId, type VRouteLazyComponent, type VRouteMatchedData, type VRouteMeta, type VRouteNormalized, type VRouteRaw, type VRouteRenderComponent, type VRouter, type VRouterData, type VRouterOptions, VRouterView, type VRoutesMap, type VirouPluginOptions, createVRouter, useVRouter, virou, virouSymbol };

package/dist/index.mjs

@@ -1,133 +1,130 @@
-import { defineAsyncComponent, shallowRef, ref, inject, useId, provide, computed, defineComponent, h, KeepAlive } from 'vue';
-import { createGlobalState } from '@vueuse/core';
+import { defineAsyncComponent, ref, shallowRef, watchEffect, inject, useId, provide, getCurrentInstance, onScopeDispose, defineComponent, h, Suspense, KeepAlive } from 'vue';
 import { addRoute, createRouter, findRoute } from 'rou3';
 import { joinURL, parseURL } from 'ufo';
 
-function addRoutes(router, routes, parentPath = "") {
-  const { context, routeTree, views, keys } = router;
-  routes.forEach(({ key, path, component, meta, children }) => {
-    const fullPath = joinURL(parentPath, path);
-    views[fullPath] ||= [];
-    views[fullPath].push(defineAsyncComponent(component));
-    keys[fullPath] ||= [];
-    keys[fullPath].push(key ?? null);
-    addRoute(context, "GET", fullPath, { key, fullPath, meta });
-    const node = [fullPath];
-    if (children) {
-      const childRouteTree = [];
-      addRoutes({ ...router, routeTree: childRouteTree }, children, fullPath);
-      node[1] = childRouteTree;
-    }
-    routeTree.push(node);
-  });
+const renderListCache = /* @__PURE__ */ new WeakMap();
+function normalizeComponent(component) {
+  if (typeof component === "function" && component.length === 0) {
+    return defineAsyncComponent(component);
+  }
+  return component;
 }
-function resolveRouteTree(routeTree, targetPath, accumulatedPaths = []) {
-  for (const [path, children] of routeTree) {
-    const paths = [...accumulatedPaths, path];
-    if (path === targetPath) {
-      return paths;
-    }
-    if (children) {
-      const result = resolveRouteTree(children, targetPath, paths);
-      if (result.length) {
-        return result;
-      }
+function registerRoutes(ctx, routes, registry, parentId) {
+  for (const { path, meta, component, children } of routes) {
+    const fullPath = joinURL(parentId?.[0] ?? "/", path);
+    const depth = (parentId?.[1] ?? -1) + 1;
+    const id = Object.freeze([fullPath, depth]);
+    registry.set(id, {
+      meta,
+      component: normalizeComponent(component),
+      parentId
+    });
+    if (children && children.length) {
+      registerRoutes(ctx, children, registry, id);
     }
+    addRoute(ctx, "GET", fullPath, { id, meta });
   }
-  return [];
 }
-function createRenderList(routes, targetPath, views, keys) {
-  const renderList = [];
-  const currentSegments = targetPath.split("/").filter(Boolean);
-  routes.forEach((path) => {
-    const treeViews = views[path];
-    const treeKeys = keys[path];
-    if (treeViews === undefined || treeKeys === undefined || treeViews.length !== treeKeys.length) {
-      throw new Error(`[virou] Mismatch or missing data for path: ${path}`);
-    }
-    const resolvedPath = joinURL("/", ...currentSegments.slice(0, path.split("/").filter(Boolean).length));
-    for (let i = 0; i < treeViews.length; i++) {
-      const view = treeViews[i];
-      const key = treeKeys[i];
-      if (view !== undefined && key !== undefined && (targetPath === resolvedPath || i === 0)) {
-        renderList.push([key ?? resolvedPath, view]);
-      }
-    }
-  });
-  return renderList;
+function createRenderList(data, routes) {
+  let cacheForRoutes = renderListCache.get(routes);
+  if (!cacheForRoutes) {
+    cacheForRoutes = /* @__PURE__ */ new Map();
+    renderListCache.set(routes, cacheForRoutes);
+  }
+  const cached = cacheForRoutes.get(data.id);
+  if (cached) {
+    return cached;
+  }
+  const depth = data.id[1];
+  const list = Array.from({ length: depth });
+  let idx = depth;
+  let cursor = routes.get(data.id);
+  while (cursor) {
+    list[idx--] = cursor.component;
+    cursor = cursor.parentId !== void 0 ? routes.get(cursor.parentId) : void 0;
+  }
+  cacheForRoutes.set(data.id, list);
+  return list;
 }
 
 const virouSymbol = Symbol("virou");
-const useVirouState = createGlobalState(() => {
-  const routers = shallowRef({});
-  const activeRoutePaths = ref({});
-  return { routers, activeRoutePaths };
-});
-function createVRouter(key, routes, options) {
-  const { routers, activeRoutePaths } = useVirouState();
-  if (key in routers.value) {
-    throw new Error(`[virou] [createVRouter] key already exists: ${key}`);
-  }
-  routers.value[key] = {
-    context: createRouter(),
-    routeTree: [],
-    views: {},
-    keys: {}
+function createVRouter(routes, options) {
+  const context = createRouter();
+  const routeRegistry = /* @__PURE__ */ new Map();
+  registerRoutes(context, routes, routeRegistry);
+  const activePath = ref(options?.initialPath ?? "/");
+  const snapshot = () => {
+    const matchedRoute = findRoute(context, "GET", activePath.value);
+    const _renderList = matchedRoute ? createRenderList(matchedRoute.data, routeRegistry) : null;
+    const { pathname, hash, search } = parseURL(activePath.value);
+    return {
+      fullPath: activePath.value,
+      path: pathname,
+      search,
+      hash,
+      meta: matchedRoute?.data.meta,
+      params: matchedRoute?.params,
+      _renderList
+    };
   };
-  addRoutes(routers.value[key], routes);
-  const { initialPath } = options ||= {
-    initialPath: "/"
+  const route = shallowRef(snapshot());
+  const unwatch = watchEffect(() => {
+    route.value = snapshot();
+  });
+  return {
+    context,
+    routes: routeRegistry,
+    activePath,
+    route,
+    _isGlobal: options?._isGlobal ?? false,
+    _deps: 0,
+    _dispose: unwatch
   };
-  activeRoutePaths.value[key] = initialPath;
 }
 function useVRouter(...args) {
   if (typeof args[0] !== "string") {
     args.unshift(inject(virouSymbol, useId()));
   }
-  const [key, routes] = args;
+  const [key, routes = [], options = {}] = args;
   if (!key || typeof key !== "string") {
     throw new TypeError(`[virou] [useVRouter] key must be a string: ${key}`);
   }
   provide(virouSymbol, key);
-  const options = args[2];
-  const { routers, activeRoutePaths } = useVirouState();
-  if (routers.value[key] === undefined) {
-    if (routes === undefined) {
-      throw new Error(`[virou] [useVRouter] routes is required for key: ${key}`);
+  const vm = getCurrentInstance();
+  if (!vm) {
+    throw new TypeError("[virou] [useVRouter] useVRouter must be called in setup()");
+  }
+  const virou = vm.proxy?.$virou;
+  if (!virou) {
+    throw new Error("[virou] [useVRouter] virou plugin not installed");
+  }
+  if (routes.length) {
+    if (virou.get(key)) {
+      throw new Error(`[virou] [useVRouter] router with key "${key}" already exists`);
     }
-    createVRouter(key, routes, options);
+    virou.set(key, createVRouter(routes, options));
   }
-  const route = computed(() => {
-    const { context, routeTree, views, keys } = routers.value[key];
-    const activeRoutePath = activeRoutePaths.value[key];
-    const matchedRoute = findRoute(
-      context,
-      "GET",
-      activeRoutePath
-    );
-    const activeRouteTree = matchedRoute && resolveRouteTree(routeTree, matchedRoute.data.fullPath);
-    const { search, pathname, hash } = parseURL(activeRoutePath);
-    const renderList = activeRouteTree && createRenderList(activeRouteTree, pathname, views, keys);
-    return {
-      fullPath: activeRoutePath,
-      ...matchedRoute,
-      search,
-      path: pathname,
-      hash,
-      activeRouteTree,
-      renderList
-    };
+  const router = virou.get(key);
+  if (!router) {
+    throw new Error(`[virou] [useVRouter] router with key "${key}" not found`);
+  }
+  router._deps++;
+  onScopeDispose(() => {
+    router._deps--;
+    if (router._deps === 0 && !router._isGlobal) {
+      router._dispose();
+      virou.delete(key);
+    }
   });
   return {
-    route,
+    route: router.route,
     router: {
-      addRoute: (route2) => {
-        addRoutes(routers.value[key], [route2]);
+      addRoute: (route) => {
+        registerRoutes(router.context, [route], router.routes);
       },
       replace: (path) => {
-        activeRoutePaths.value[key] = path;
+        router.activePath.value = path;
       },
-      _key: key,
       _depthKey: Symbol.for(key)
     }
   };
@@ -135,36 +132,51 @@ function useVRouter(...args) {
 
 const VRouterView = defineComponent({
   name: "VRouterView",
+  inheritAttrs: false,
   props: {
-    routerKey: {
-      type: String,
-      default: undefined
-    },
-    viewKey: {
-      type: String,
-      default: undefined
-    },
-    keepalive: {
-      type: Boolean,
-      default: false
-    }
+    routerKey: String,
+    keepAlive: { type: Boolean, default: false },
+    viewKey: { type: [String, Function] }
   },
-  setup(props) {
-    const routerKey = props.routerKey ?? inject(virouSymbol);
-    if (routerKey === undefined) {
-      throw new Error(`[virou] [VRouterView] routerKey is required`);
+  slots: Object,
+  setup(props, { slots, attrs }) {
+    const key = props.routerKey ?? inject(virouSymbol);
+    if (key === void 0) {
+      throw new Error("[virou] [VRouterView] routerKey is required");
     }
-    const { router, route } = useVRouter(routerKey);
+    const { route, router } = useVRouter(key);
     const depth = inject(router._depthKey, 0);
-    const render = computed(() => route.value.renderList?.[depth]);
     provide(router._depthKey, depth + 1);
     return () => {
-      const [key, component] = render.value ?? [];
-      const _key = key ?? props.viewKey ?? route.value.path;
-      const ViewComponent = component !== null && component !== undefined ? h(component, { _key }) : null;
-      return props.keepalive ? h(KeepAlive, null, [ViewComponent]) : ViewComponent;
+      const component = route.value._renderList?.[depth];
+      if (!component) {
+        return slots.default?.({ Component: null, route: route.value }) ?? null;
+      }
+      const vnodeKey = typeof props.viewKey === "function" ? props.viewKey(route.value, key) : props.viewKey ?? `${key}-${depth}-${route.value.path}`;
+      const suspenseVNode = h(
+        Suspense,
+        null,
+        {
+          default: () => h(component, { key: vnodeKey, ...attrs }),
+          fallback: () => slots.fallback?.({ route: route.value }) ?? null
+        }
+      );
+      const vnode = props.keepAlive ? h(KeepAlive, null, { default: () => suspenseVNode }) : suspenseVNode;
+      return slots.default?.({ Component: vnode, route: route.value }) ?? vnode;
     };
   }
 });
 
-export { VRouterView, createVRouter, useVRouter, virouSymbol };
+const virou = (app, options = {}) => {
+  const { routers } = options;
+  const map = /* @__PURE__ */ new Map();
+  app.config.globalProperties.$virou = map;
+  app.component("VRouterView", VRouterView);
+  if (routers) {
+    for (const [key, router] of Object.entries(routers)) {
+      map.set(key, createVRouter(router.routes, { ...router.options, _isGlobal: true }));
+    }
+  }
+};
+
+export { VRouterView, createVRouter, useVRouter, virou, virouSymbol };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@virou/core",
   "type": "module",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Virtual router with multiple instance support for Vue",
   "author": "Tankosin<https://github.com/tankosinn>",
   "license": "MIT",
@@ -22,32 +22,21 @@
   ],
   "sideEffects": false,
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": {
-        "types": "./dist/index.d.mts",
-        "default": "./dist/index.mjs"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
-    }
+    "types": "./dist/index.d.mts",
+    "default": "./dist/index.mjs"
   },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.cts",
   "files": [
     "dist"
   ],
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
   "dependencies": {
-    "@vueuse/core": "^12.4.0",
-    "rou3": "^0.5.1",
-    "ufo": "^1.5.4",
-    "vue": "^3.5.13"
+    "rou3": "^0.6.1",
+    "ufo": "^1.6.1"
   },
   "devDependencies": {
-    "unbuild": "3.3.1"
+    "unbuild": "3.5.0"
   },
   "scripts": {
     "build": "unbuild"

package/dist/index.cjs

@@ -1,175 +0,0 @@
-'use strict';
-
-const vue = require('vue');
-const core = require('@vueuse/core');
-const rou3 = require('rou3');
-const ufo = require('ufo');
-
-function addRoutes(router, routes, parentPath = "") {
-  const { context, routeTree, views, keys } = router;
-  routes.forEach(({ key, path, component, meta, children }) => {
-    const fullPath = ufo.joinURL(parentPath, path);
-    views[fullPath] ||= [];
-    views[fullPath].push(vue.defineAsyncComponent(component));
-    keys[fullPath] ||= [];
-    keys[fullPath].push(key ?? null);
-    rou3.addRoute(context, "GET", fullPath, { key, fullPath, meta });
-    const node = [fullPath];
-    if (children) {
-      const childRouteTree = [];
-      addRoutes({ ...router, routeTree: childRouteTree }, children, fullPath);
-      node[1] = childRouteTree;
-    }
-    routeTree.push(node);
-  });
-}
-function resolveRouteTree(routeTree, targetPath, accumulatedPaths = []) {
-  for (const [path, children] of routeTree) {
-    const paths = [...accumulatedPaths, path];
-    if (path === targetPath) {
-      return paths;
-    }
-    if (children) {
-      const result = resolveRouteTree(children, targetPath, paths);
-      if (result.length) {
-        return result;
-      }
-    }
-  }
-  return [];
-}
-function createRenderList(routes, targetPath, views, keys) {
-  const renderList = [];
-  const currentSegments = targetPath.split("/").filter(Boolean);
-  routes.forEach((path) => {
-    const treeViews = views[path];
-    const treeKeys = keys[path];
-    if (treeViews === undefined || treeKeys === undefined || treeViews.length !== treeKeys.length) {
-      throw new Error(`[virou] Mismatch or missing data for path: ${path}`);
-    }
-    const resolvedPath = ufo.joinURL("/", ...currentSegments.slice(0, path.split("/").filter(Boolean).length));
-    for (let i = 0; i < treeViews.length; i++) {
-      const view = treeViews[i];
-      const key = treeKeys[i];
-      if (view !== undefined && key !== undefined && (targetPath === resolvedPath || i === 0)) {
-        renderList.push([key ?? resolvedPath, view]);
-      }
-    }
-  });
-  return renderList;
-}
-
-const virouSymbol = Symbol("virou");
-const useVirouState = core.createGlobalState(() => {
-  const routers = vue.shallowRef({});
-  const activeRoutePaths = vue.ref({});
-  return { routers, activeRoutePaths };
-});
-function createVRouter(key, routes, options) {
-  const { routers, activeRoutePaths } = useVirouState();
-  if (key in routers.value) {
-    throw new Error(`[virou] [createVRouter] key already exists: ${key}`);
-  }
-  routers.value[key] = {
-    context: rou3.createRouter(),
-    routeTree: [],
-    views: {},
-    keys: {}
-  };
-  addRoutes(routers.value[key], routes);
-  const { initialPath } = options ||= {
-    initialPath: "/"
-  };
-  activeRoutePaths.value[key] = initialPath;
-}
-function useVRouter(...args) {
-  if (typeof args[0] !== "string") {
-    args.unshift(vue.inject(virouSymbol, vue.useId()));
-  }
-  const [key, routes] = args;
-  if (!key || typeof key !== "string") {
-    throw new TypeError(`[virou] [useVRouter] key must be a string: ${key}`);
-  }
-  vue.provide(virouSymbol, key);
-  const options = args[2];
-  const { routers, activeRoutePaths } = useVirouState();
-  if (routers.value[key] === undefined) {
-    if (routes === undefined) {
-      throw new Error(`[virou] [useVRouter] routes is required for key: ${key}`);
-    }
-    createVRouter(key, routes, options);
-  }
-  const route = vue.computed(() => {
-    const { context, routeTree, views, keys } = routers.value[key];
-    const activeRoutePath = activeRoutePaths.value[key];
-    const matchedRoute = rou3.findRoute(
-      context,
-      "GET",
-      activeRoutePath
-    );
-    const activeRouteTree = matchedRoute && resolveRouteTree(routeTree, matchedRoute.data.fullPath);
-    const { search, pathname, hash } = ufo.parseURL(activeRoutePath);
-    const renderList = activeRouteTree && createRenderList(activeRouteTree, pathname, views, keys);
-    return {
-      fullPath: activeRoutePath,
-      ...matchedRoute,
-      search,
-      path: pathname,
-      hash,
-      activeRouteTree,
-      renderList
-    };
-  });
-  return {
-    route,
-    router: {
-      addRoute: (route2) => {
-        addRoutes(routers.value[key], [route2]);
-      },
-      replace: (path) => {
-        activeRoutePaths.value[key] = path;
-      },
-      _key: key,
-      _depthKey: Symbol.for(key)
-    }
-  };
-}
-
-const VRouterView = vue.defineComponent({
-  name: "VRouterView",
-  props: {
-    routerKey: {
-      type: String,
-      default: undefined
-    },
-    viewKey: {
-      type: String,
-      default: undefined
-    },
-    keepalive: {
-      type: Boolean,
-      default: false
-    }
-  },
-  setup(props) {
-    const routerKey = props.routerKey ?? vue.inject(virouSymbol);
-    if (routerKey === undefined) {
-      throw new Error(`[virou] [VRouterView] routerKey is required`);
-    }
-    const { router, route } = useVRouter(routerKey);
-    const depth = vue.inject(router._depthKey, 0);
-    const render = vue.computed(() => route.value.renderList?.[depth]);
-    vue.provide(router._depthKey, depth + 1);
-    return () => {
-      const [key, component] = render.value ?? [];
-      const _key = key ?? props.viewKey ?? route.value.path;
-      const ViewComponent = component !== null && component !== undefined ? vue.h(component, { _key }) : null;
-      return props.keepalive ? vue.h(vue.KeepAlive, null, [ViewComponent]) : ViewComponent;
-    };
-  }
-});
-
-exports.VRouterView = VRouterView;
-exports.createVRouter = createVRouter;
-exports.useVRouter = useVRouter;
-exports.virouSymbol = virouSymbol;

package/dist/index.d.cts

@@ -1,99 +0,0 @@
-import * as vue from 'vue';
-import { Component, AsyncComponentLoader, ComputedRef } from 'vue';
-import { RouterContext } from 'rou3';
-
-declare const VRouterView: vue.DefineComponent<vue.ExtractPropTypes<{
-    routerKey: {
-        type: StringConstructor;
-        default: undefined;
-    };
-    viewKey: {
-        type: StringConstructor;
-        default: undefined;
-    };
-    keepalive: {
-        type: BooleanConstructor;
-        default: boolean;
-    };
-}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
-    [key: string]: any;
-}> | null, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
-    routerKey: {
-        type: StringConstructor;
-        default: undefined;
-    };
-    viewKey: {
-        type: StringConstructor;
-        default: undefined;
-    };
-    keepalive: {
-        type: BooleanConstructor;
-        default: boolean;
-    };
-}>> & Readonly<{}>, {
-    routerKey: string;
-    viewKey: string;
-    keepalive: boolean;
-}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
-
-type VRouteTreeNode = [key: string, children?: VRouteTreeNode[]];
-type VRouteViews = Record<string, Component[]>;
-type VRouteKeys = Record<string, Array<string | null>>;
-type VRouteRenderView = [key: string, component: Component];
-interface VRouteRecordRaw {
-    key?: string;
-    path: string;
-    component: AsyncComponentLoader<Component>;
-    meta?: Record<string, any>;
-    children?: VRouteRecordRaw[];
-}
-interface VRouteMatchedData {
-    key?: string;
-    fullPath: string;
-    meta?: Record<string, any>;
-}
-interface VRouterInstance {
-    context: RouterContext<VRouteMatchedData>;
-    routeTree: VRouteTreeNode[];
-    views: VRouteViews;
-    keys: VRouteKeys;
-}
-interface VRouterOptions {
-    initialPath: string;
-}
-interface VRouter {
-    route: ComputedRef<{
-        fullPath: string;
-        data?: VRouteMatchedData;
-        params?: Record<string, string>;
-        path: string;
-        search: string;
-        hash: string;
-        activeRouteTree?: string[];
-        renderList?: VRouteRenderView[];
-    }>;
-    router: {
-        addRoute: (route: VRouteRecordRaw) => void;
-        replace: (path: string) => void;
-        _key: string;
-        _depthKey: symbol;
-    };
-}
-
-declare const virouSymbol: unique symbol;
-declare function createVRouter(key: string, routes: VRouteRecordRaw[], options?: VRouterOptions): void;
-/**
- * Creates or retrieves a virtual router
- *
- * @param key - a unique identifier for the router
- * @param routes - a list of routes to add to the router
- * @param options - configuration options for the router
- *
- * @returns an object containing:
- *   - `route`: reactive data for the current route (e.g., path, fullPath, query, etc.)
- *   - `router`: utilities to manage the router (e.g., `addRoute`, `replace`)
- */
-declare function useVRouter(key?: string, routes?: VRouteRecordRaw[], options?: VRouterOptions): VRouter;
-declare function useVRouter(routes?: VRouteRecordRaw[], options?: VRouterOptions): VRouter;
-
-export { type VRouteKeys, type VRouteMatchedData, type VRouteRecordRaw, type VRouteRenderView, type VRouteTreeNode, type VRouteViews, type VRouter, type VRouterInstance, type VRouterOptions, VRouterView, createVRouter, useVRouter, virouSymbol };

package/dist/index.d.ts

@@ -1,99 +0,0 @@
-import * as vue from 'vue';
-import { Component, AsyncComponentLoader, ComputedRef } from 'vue';
-import { RouterContext } from 'rou3';
-
-declare const VRouterView: vue.DefineComponent<vue.ExtractPropTypes<{
-    routerKey: {
-        type: StringConstructor;
-        default: undefined;
-    };
-    viewKey: {
-        type: StringConstructor;
-        default: undefined;
-    };
-    keepalive: {
-        type: BooleanConstructor;
-        default: boolean;
-    };
-}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
-    [key: string]: any;
-}> | null, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
-    routerKey: {
-        type: StringConstructor;
-        default: undefined;
-    };
-    viewKey: {
-        type: StringConstructor;
-        default: undefined;
-    };
-    keepalive: {
-        type: BooleanConstructor;
-        default: boolean;
-    };
-}>> & Readonly<{}>, {
-    routerKey: string;
-    viewKey: string;
-    keepalive: boolean;
-}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
-
-type VRouteTreeNode = [key: string, children?: VRouteTreeNode[]];
-type VRouteViews = Record<string, Component[]>;
-type VRouteKeys = Record<string, Array<string | null>>;
-type VRouteRenderView = [key: string, component: Component];
-interface VRouteRecordRaw {
-    key?: string;
-    path: string;
-    component: AsyncComponentLoader<Component>;
-    meta?: Record<string, any>;
-    children?: VRouteRecordRaw[];
-}
-interface VRouteMatchedData {
-    key?: string;
-    fullPath: string;
-    meta?: Record<string, any>;
-}
-interface VRouterInstance {
-    context: RouterContext<VRouteMatchedData>;
-    routeTree: VRouteTreeNode[];
-    views: VRouteViews;
-    keys: VRouteKeys;
-}
-interface VRouterOptions {
-    initialPath: string;
-}
-interface VRouter {
-    route: ComputedRef<{
-        fullPath: string;
-        data?: VRouteMatchedData;
-        params?: Record<string, string>;
-        path: string;
-        search: string;
-        hash: string;
-        activeRouteTree?: string[];
-        renderList?: VRouteRenderView[];
-    }>;
-    router: {
-        addRoute: (route: VRouteRecordRaw) => void;
-        replace: (path: string) => void;
-        _key: string;
-        _depthKey: symbol;
-    };
-}
-
-declare const virouSymbol: unique symbol;
-declare function createVRouter(key: string, routes: VRouteRecordRaw[], options?: VRouterOptions): void;
-/**
- * Creates or retrieves a virtual router
- *
- * @param key - a unique identifier for the router
- * @param routes - a list of routes to add to the router
- * @param options - configuration options for the router
- *
- * @returns an object containing:
- *   - `route`: reactive data for the current route (e.g., path, fullPath, query, etc.)
- *   - `router`: utilities to manage the router (e.g., `addRoute`, `replace`)
- */
-declare function useVRouter(key?: string, routes?: VRouteRecordRaw[], options?: VRouterOptions): VRouter;
-declare function useVRouter(routes?: VRouteRecordRaw[], options?: VRouterOptions): VRouter;
-
-export { type VRouteKeys, type VRouteMatchedData, type VRouteRecordRaw, type VRouteRenderView, type VRouteTreeNode, type VRouteViews, type VRouter, type VRouterInstance, type VRouterOptions, VRouterView, createVRouter, useVRouter, virouSymbol };