@esmx/router-vue 3.0.0-rc.103

package/dist/run-with-context.test.mjs

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import {
+  createApp,
+  getCurrentInstance,
+  h,
+  inject,
+  nextTick,
+  provide
+} from "vue";
+describe("app.runWithContext()", () => {
+  it("should exist on Vue app", () => {
+    const app = createApp({ render: () => h("div") });
+    expect(typeof app.runWithContext).toBe("function");
+  });
+  it("should enable inject to read provided value within context", () => {
+    const KEY = Symbol("ctx-key");
+    const app = createApp({ render: () => h("div") });
+    app.provide(KEY, 42);
+    const value = app.runWithContext(() => inject(KEY));
+    expect(value).toBe(42);
+  });
+  it("should not read value provided in root setup via runWithContext", async () => {
+    const KEY = Symbol("ctx-key-setup");
+    const app = createApp({
+      setup() {
+        provide(KEY, 7);
+        return () => h("div");
+      }
+    });
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    app.mount(container);
+    await nextTick();
+    const value = app.runWithContext(() => inject(KEY));
+    expect(value).toBeUndefined();
+    app.unmount();
+    container.remove();
+  });
+  it("should read app-level provide set inside setup via appContext", async () => {
+    const KEY = Symbol("ctx-key-setup-app");
+    const app = createApp({
+      setup() {
+        const appInst = getCurrentInstance().appContext.app;
+        appInst.provide(KEY, 9);
+        return () => h("div");
+      }
+    });
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    app.mount(container);
+    await nextTick();
+    const value = app.runWithContext(() => inject(KEY));
+    expect(value).toBe(9);
+    app.unmount();
+    container.remove();
+  });
+});

package/dist/use.d.ts

@@ -0,0 +1,260 @@
+import type { Route, Router, RouterLinkProps } from '@esmx/router';
+export interface VueInstance {
+    $parent?: VueInstance | null;
+    $root?: VueInstance | null;
+    $children?: VueInstance[] | null;
+}
+/**
+ * Get router instance from a Vue component instance.
+ * This is a lower-level function used internally by useRouter().
+ * Use this in Options API, use useRouter() in Composition API.
+ *
+ * @param instance - Vue component instance
+ * @returns Router instance
+ * @throws {Error} If router context is not found
+ *
+ * @example
+ * ```typescript
+ * // Options API usage
+ * import { defineComponent } from 'vue';
+ * import { getRouter } from '@esmx/router-vue';
+ *
+ * export default defineComponent({
+ *   mounted() {
+ *     const router = getRouter(this);
+ *     router.push('/dashboard');
+ *   },
+ *   methods: {
+ *     handleNavigation() {
+ *       const router = getRouter(this);
+ *       router.replace('/profile');
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare function getRouter(instance: VueInstance): Router;
+/**
+ * Get current route from a Vue component instance.
+ * This is a lower-level function used internally by useRoute().
+ * Use this in Options API, use useRoute() in Composition API.
+ *
+ * @param instance - Vue component instance
+ * @returns Current route object
+ * @throws {Error} If router context is not found
+ *
+ * @example
+ * ```typescript
+ * // Options API usage
+ * import { defineComponent } from 'vue';
+ * import { getRoute } from '@esmx/router-vue';
+ *
+ * export default defineComponent({
+ *   computed: {
+ *     routeInfo() {
+ *       const route = getRoute(this);
+ *       return {
+ *         path: route.path,
+ *         params: route.params,
+ *         query: route.query
+ *       };
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare function getRoute(instance: VueInstance): Route;
+/**
+ * Get the router instance in a Vue component.
+ * Must be called within setup() or other composition functions.
+ * Use this in Composition API, use getRouter() in Options API.
+ *
+ * @returns Router instance for navigation and route management
+ * @throws {Error} If called outside setup() or router context not found
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useRouter } from '@esmx/router-vue';
+ *
+ * const router = useRouter();
+ *
+ * const navigateToHome = () => {
+ *   router.push('/home');
+ * };
+ *
+ * const goBack = () => {
+ *   router.back();
+ * };
+ *
+ * const navigateWithQuery = () => {
+ *   router.push({
+ *     path: '/search',
+ *     query: { q: 'vue router', page: '1' }
+ *   });
+ * };
+ * </script>
+ * ```
+ */
+export declare function useRouter(): Router;
+/**
+ * Get the current route information in a Vue component.
+ * Returns a reactive reference that automatically updates when the route changes.
+ * Must be called within setup() or other composition functions.
+ * Use this in Composition API, use getRoute() in Options API.
+ *
+ * @returns Current route object with path, params, query, etc.
+ * @throws {Error} If called outside setup() or router context not found
+ *
+ * @example
+ * ```vue
+ * <template>
+ *   <div>
+ *     <h1>{{ route.meta?.title || 'Page' }}</h1>
+ *     <p>Path: {{ route.path }}</p>
+ *     <p>Params: {{ JSON.stringify(route.params) }}</p>
+ *     <p>Query: {{ JSON.stringify(route.query) }}</p>
+ *   </div>
+ * </template>
+ *
+ * <script setup lang="ts">
+ * import { useRoute } from '@esmx/router-vue';
+ * import { watch } from 'vue';
+ *
+ * const route = useRoute();
+ *
+ * watch(() => route.path, (newPath) => {
+ *   console.log('Route changed to:', newPath);
+ * });
+ * </script>
+ * ```
+ */
+export declare function useRoute(): Route;
+/**
+ * Provide router context to child components.
+ * This must be called in a parent component to make the router available
+ * to child components via useRouter() and useRoute().
+ *
+ * @param router - Router instance to provide to child components
+ * @throws {Error} If called outside setup()
+ *
+ * @example
+ * ```typescript
+ * // Vue 3 usage
+ * import { createApp } from 'vue';
+ * import { Router } from '@esmx/router';
+ * import { useProvideRouter } from '@esmx/router-vue';
+ *
+ * const routes = [
+ *   { path: '/', component: () => import('./Home.vue') },
+ *   { path: '/about', component: () => import('./About.vue') }
+ * ];
+ *
+ * const router = new Router({ routes });
+ * const app = createApp({
+ *   setup() {
+ *     useProvideRouter(router);
+ *   }
+ * });
+ * app.mount('#app');
+ * ```
+ */
+export declare function useProvideRouter(router: Router): void;
+/**
+ * Get the current RouterView depth in nested routing scenarios.
+ * Returns the depth of the current RouterView component in the component tree.
+ * Useful for advanced routing scenarios where you need to know the nesting level.
+ *
+ * @param isRender - Whether this is used in a RouterView component that needs to provide depth for children (default: false)
+ * @returns Current RouterView depth (0 for root level, 1 for first nested level, etc.)
+ * @throws {Error} If called outside setup()
+ *
+ * @example
+ * ```vue
+ * <template>
+ *   <div>
+ *     <p>Current RouterView depth: {{ depth }}</p>
+ *     <RouterView />
+ *   </div>
+ * </template>
+ *
+ * <script setup lang="ts">
+ * import { useRouterViewDepth } from '@esmx/router-vue';
+ *
+ * // Get current depth without providing for children
+ * const depth = useRouterViewDepth();
+ * console.log('Current RouterView depth:', depth); // 0, 1, 2, etc.
+ *
+ * // Get current depth and provide depth + 1 for children (used in RouterView component)
+ * const depth = useRouterViewDepth(true);
+ * </script>
+ * ```
+ */
+export declare function _useRouterViewDepth(isRender?: boolean): number;
+/**
+ * Get the current RouterView depth in nested routing scenarios.
+ * Returns the depth of the current RouterView component in the component tree.
+ * Useful for advanced routing scenarios where you need to know the nesting level.
+ *
+ * @returns Current RouterView depth (0 for root level, 1 for first nested level, etc.)
+ * @throws {Error} If called outside setup()
+ *
+ * @example
+ * ```vue
+ * <template>
+ *   <div>
+ *     <p>Current RouterView depth: {{ depth }}</p>
+ *     <RouterView />
+ *   </div>
+ * </template>
+ *
+ * <script setup lang="ts">
+ * import { useRouterViewDepth } from '@esmx/router-vue';
+ *
+ * // Get current depth without providing for children
+ * const depth = useRouterViewDepth();
+ * console.log('Current RouterView depth:', depth); // 0, 1, 2, etc.
+ * </script>
+ * ```
+ */
+export declare function useRouterViewDepth(): number;
+/**
+ * Get injected RouterView depth from a Vue instance's ancestors.
+ * Traverses parent chain to find the value provided under ROUTER_VIEW_DEPTH_KEY.
+ *
+ * @param instance - Vue component instance to start from
+ * @returns Injected RouterView depth value from nearest ancestor
+ * @throws {Error} If no ancestor provided ROUTER_VIEW_DEPTH_KEY
+ */
+export declare function getRouterViewDepth(instance: VueInstance): number;
+/**
+ * Create reactive link helpers for navigation elements.
+ * Returns computed properties for link attributes, classes, and event handlers.
+ *
+ * @param props - RouterLink properties configuration
+ * @returns Computed link resolver with attributes and event handlers
+ *
+ * @example
+ * ```vue
+ * <template>
+ *   <a
+ *     v-bind="link.attributes"
+ *     v-on="link.createEventHandlers()"
+ *     :class="{ active: link.isActive }"
+ *   >
+ *     Home
+ *   </a>
+ * </template>
+ *
+ * <script setup lang="ts">
+ * import { useLink } from '@esmx/router-vue';
+ *
+ * const link = useLink({
+ *   to: '/home',
+ *   type: 'push',
+ *   exact: 'include'
+ * }).value;
+ * </script>
+ * ```
+ */
+export declare function useLink(props: RouterLinkProps): import("vue").ComputedRef<import("@esmx/router").RouterLinkResolved>;

package/dist/use.mjs

@@ -0,0 +1,125 @@
+import {
+  computed,
+  getCurrentInstance,
+  inject,
+  onBeforeUnmount,
+  provide,
+  ref
+} from "vue";
+import {
+  createDependentProxy,
+  createSymbolProperty,
+  defineRouterProperties,
+  isVue2
+} from "./util.mjs";
+const ROUTER_CONTEXT_KEY = Symbol("router-context");
+const ROUTER_INJECT_KEY = Symbol("router-inject");
+const ROUTER_VIEW_DEPTH_KEY = Symbol("router-view-depth");
+const routerContextProperty = createSymbolProperty(ROUTER_CONTEXT_KEY);
+const routerViewDepthProperty = createSymbolProperty(
+  ROUTER_VIEW_DEPTH_KEY
+);
+function getCurrentProxy() {
+  const instance = getCurrentInstance();
+  if (!instance || !instance.proxy) {
+    throw new Error(
+      "[@esmx/router-vue] Must be used within setup() or other composition functions"
+    );
+  }
+  return instance.proxy;
+}
+function findRouterContext(vm) {
+  let context = routerContextProperty.get(vm);
+  if (context) {
+    return context;
+  }
+  let current = vm.$parent;
+  while (current) {
+    context = routerContextProperty.get(current);
+    if (context) {
+      routerContextProperty.set(vm, context);
+      return context;
+    }
+    current = current.$parent;
+  }
+  throw new Error(
+    "[@esmx/router-vue] Router context not found. Please ensure useProvideRouter() is called in a parent component."
+  );
+}
+export function getRouter(instance) {
+  return findRouterContext(instance).router;
+}
+export function getRoute(instance) {
+  return findRouterContext(instance).route;
+}
+function useRouterContext() {
+  const injectedContext = inject(ROUTER_INJECT_KEY);
+  if (injectedContext) {
+    return injectedContext;
+  }
+  const proxy = getCurrentProxy();
+  return findRouterContext(proxy);
+}
+export function useRouter() {
+  return useRouterContext().router;
+}
+export function useRoute() {
+  return useRouterContext().route;
+}
+export function useProvideRouter(router) {
+  const proxy = getCurrentProxy();
+  const dep = ref(0);
+  const proxiedRouter = createDependentProxy(router, dep);
+  const proxiedRoute = createDependentProxy(router.route, dep);
+  const context = {
+    router: proxiedRouter,
+    route: proxiedRoute
+  };
+  provide(ROUTER_INJECT_KEY, context);
+  routerContextProperty.set(proxy, context);
+  if (!isVue2) {
+    const app = getCurrentInstance().appContext.app;
+    defineRouterProperties(
+      app.config.globalProperties,
+      () => proxiedRouter,
+      () => proxiedRoute,
+      true
+    );
+  }
+  const unwatch = router.afterEach((to) => {
+    if (router.route === to) {
+      to.syncTo(proxiedRoute);
+      dep.value++;
+    }
+  });
+  onBeforeUnmount(unwatch);
+}
+export function _useRouterViewDepth(isRender) {
+  const depth = inject(ROUTER_VIEW_DEPTH_KEY, 0);
+  if (isRender) {
+    provide(ROUTER_VIEW_DEPTH_KEY, depth + 1);
+    const proxy = getCurrentProxy();
+    routerViewDepthProperty.set(proxy, depth + 1);
+  }
+  return depth;
+}
+export function useRouterViewDepth() {
+  return _useRouterViewDepth();
+}
+export function getRouterViewDepth(instance) {
+  let current = instance.$parent;
+  while (current) {
+    const value = routerViewDepthProperty.get(current);
+    if (typeof value === "number") return value;
+    current = current.$parent;
+  }
+  throw new Error(
+    "[@esmx/router-vue] RouterView depth not found. Please ensure a RouterView exists in ancestor components."
+  );
+}
+export function useLink(props) {
+  const router = useRouter();
+  return computed(() => {
+    return router.resolveLink(props);
+  });
+}

package/dist/use.test.d.ts

@@ -0,0 +1 @@
+export {};