@real-router/vue 0.3.3 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/vue",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "type": "commonjs",
   "description": "Vue 3 integration for Real-Router",
   "main": "./dist/cjs/index.js",
@@ -8,7 +8,6 @@
   "types": "./dist/esm/index.d.mts",
   "exports": {
     ".": {
-      "development": "./src/index.ts",
       "types": {
         "import": "./dist/esm/index.d.mts",
         "require": "./dist/cjs/index.d.ts"
@@ -18,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "homepage": "https://github.com/greydragon888/real-router",
   "repository": {
@@ -49,15 +49,15 @@
   "license": "MIT",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/route-utils": "^0.1.12",
-    "@real-router/core": "^0.45.1",
-    "@real-router/sources": "^0.4.2"
+    "@real-router/core": "^0.45.2",
+    "@real-router/route-utils": "^0.1.13",
+    "@real-router/sources": "^0.4.3"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "6.9.1",
     "@vue/test-utils": "2.4.6",
     "vue": "3.5.13",
-    "@real-router/browser-plugin": "^0.11.5",
+    "@real-router/browser-plugin": "^0.11.6",
     "dom-utils": "^0.2.7"
   },
   "peerDependencies": {
@@ -69,7 +69,7 @@
     "test:stress": "vitest run --config vitest.config.stress.mts",
     "type-check": "tsc --noEmit",
     "lint": "eslint --cache src/ tests/ --fix --max-warnings 0",
-    "lint:package": "bash ../../scripts/publint-filter.sh",
+    "lint:package": "publint",
     "lint:types": "attw --pack .",
     "build:dist-only": "tsdown --config-loader unrun"
   }

package/src/RouterProvider.ts

@@ -0,0 +1,69 @@
+import { getNavigator } from "@real-router/core";
+import { createRouteSource } from "@real-router/sources";
+import { createRouteAnnouncer } from "dom-utils";
+import {
+  defineComponent,
+  onMounted,
+  onUnmounted,
+  provide,
+  shallowRef,
+  onScopeDispose,
+} from "vue";
+
+import { NavigatorKey, RouteKey, RouterKey } from "./context";
+import { setDirectiveRouter } from "./directives/vLink";
+
+import type { Router } from "@real-router/core";
+import type { PropType } from "vue";
+
+export const RouterProvider = defineComponent({
+  name: "RouterProvider",
+  props: {
+    router: {
+      type: Object as PropType<Router>,
+      required: true,
+    },
+    announceNavigation: {
+      type: Boolean,
+      default: false,
+    },
+  },
+  setup(props, { slots }) {
+    onMounted(() => {
+      if (!props.announceNavigation) {
+        return;
+      }
+
+      const announcer = createRouteAnnouncer(props.router);
+
+      onUnmounted(() => {
+        announcer.destroy();
+      });
+    });
+
+    const navigator = getNavigator(props.router);
+
+    setDirectiveRouter(props.router);
+
+    const source = createRouteSource(props.router);
+    const initialSnapshot = source.getSnapshot();
+
+    const route = shallowRef(initialSnapshot.route);
+    const previousRoute = shallowRef(initialSnapshot.previousRoute);
+
+    const unsub = source.subscribe(() => {
+      const snapshot = source.getSnapshot();
+
+      route.value = snapshot.route;
+      previousRoute.value = snapshot.previousRoute;
+    });
+
+    onScopeDispose(unsub);
+
+    provide(RouterKey, props.router);
+    provide(NavigatorKey, navigator);
+    provide(RouteKey, { navigator, route, previousRoute });
+
+    return () => slots.default?.();
+  },
+});

package/src/components/Link.ts

@@ -0,0 +1,97 @@
+import { shouldNavigate, buildHref, buildActiveClassName } from "dom-utils";
+import { defineComponent, h, computed } from "vue";
+
+import { useIsActiveRoute } from "../composables/useIsActiveRoute";
+import { useRouter } from "../composables/useRouter";
+import { EMPTY_PARAMS, EMPTY_OPTIONS } from "../constants";
+
+import type { Params, NavigationOptions } from "@real-router/core";
+import type { PropType } from "vue";
+
+export const Link = defineComponent({
+  name: "Link",
+  props: {
+    routeName: {
+      type: String,
+      required: true,
+    },
+    routeParams: {
+      type: Object as PropType<Params>,
+      default: () => EMPTY_PARAMS,
+    },
+    routeOptions: {
+      type: Object as PropType<NavigationOptions>,
+      default: () => EMPTY_OPTIONS,
+    },
+    class: {
+      type: String,
+      default: undefined,
+    },
+    activeClassName: {
+      type: String,
+      default: "active",
+    },
+    activeStrict: {
+      type: Boolean,
+      default: false,
+    },
+    ignoreQueryParams: {
+      type: Boolean,
+      default: true,
+    },
+    target: {
+      type: String,
+      default: undefined,
+    },
+  },
+  setup(props, { slots, attrs }) {
+    const router = useRouter();
+
+    const isActive = useIsActiveRoute(
+      props.routeName,
+      props.routeParams,
+      props.activeStrict,
+      props.ignoreQueryParams,
+    );
+
+    const href = computed(() =>
+      buildHref(router, props.routeName, props.routeParams),
+    );
+
+    const finalClassName = computed(() =>
+      buildActiveClassName(isActive.value, props.activeClassName, props.class),
+    );
+
+    const handleClick = (evt: MouseEvent) => {
+      if (attrs.onClick && typeof attrs.onClick === "function") {
+        (attrs.onClick as (evt: MouseEvent) => void)(evt);
+
+        if (evt.defaultPrevented) {
+          return;
+        }
+      }
+
+      if (!shouldNavigate(evt) || props.target === "_blank") {
+        return;
+      }
+
+      evt.preventDefault();
+      router
+        .navigate(props.routeName, props.routeParams, props.routeOptions)
+        .catch(() => {});
+    };
+
+    return () =>
+      h(
+        "a",
+        {
+          ...attrs,
+          href: href.value,
+          class: finalClassName.value,
+          target: props.target,
+          onClick: handleClick,
+        },
+        slots.default?.(),
+      );
+  },
+});

package/src/components/RouteView/RouteView.ts

@@ -0,0 +1,210 @@
+import {
+  Fragment,
+  defineComponent,
+  h,
+  KeepAlive,
+  markRaw,
+  Suspense,
+} from "vue";
+
+import { Match, NotFound } from "./components";
+import { buildRenderList, collectElements } from "./helpers";
+import { useRouteNode } from "../../composables/useRouteNode";
+
+import type { Component, VNode } from "vue";
+
+type SlotChildren = Record<string, (() => VNode[]) | undefined> | null;
+
+function getSlotContent(vnode: VNode): VNode[] | null {
+  const slots = vnode.children as SlotChildren;
+
+  return slots?.default?.() ?? null;
+}
+
+function getOrCreateWrapper(
+  cache: Map<string, Component>,
+  segment: string,
+): Component {
+  const existing = cache.get(segment);
+
+  if (existing) {
+    return existing;
+  }
+
+  const wrapper = markRaw(
+    defineComponent({
+      name: `KeepAlive-${segment}`,
+      setup(_wrapperProps, wrapperCtx) {
+        return () => wrapperCtx.slots.default?.();
+      },
+    }),
+  );
+
+  cache.set(segment, wrapper);
+
+  return wrapper;
+}
+
+function wrapWithSuspense(content: VNode, fallback: unknown): VNode {
+  if (fallback === undefined) {
+    return content;
+  }
+
+  const fallbackContent =
+    typeof fallback === "function" ? (fallback as () => VNode)() : fallback;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment
+  const suspenseComponent = Suspense as any;
+
+  return h(
+    suspenseComponent,
+    {},
+    {
+      default: () => content,
+      fallback: () => fallbackContent,
+    },
+  );
+}
+
+const emptyKeepAlivePlaceholder = markRaw(
+  defineComponent({
+    name: "KeepAlive-placeholder",
+    render() {
+      return null;
+    },
+  }),
+);
+
+function renderWithRootKA(
+  activeChild: VNode,
+  wrapperCache: Map<string, Component>,
+  fallback: unknown,
+): VNode {
+  const activeProps = activeChild.props as { segment?: string } | null;
+  const segment = activeProps?.segment ?? "__not-found__";
+  const WrapperComponent = getOrCreateWrapper(wrapperCache, segment);
+  const slotContent = getSlotContent(activeChild) ?? [];
+  const keepAliveContent = h(KeepAlive, null, {
+    default: () =>
+      h(WrapperComponent, { key: segment }, { default: () => slotContent }),
+  });
+
+  return wrapWithSuspense(keepAliveContent, fallback);
+}
+
+function renderWithPerMatchKA(
+  activeChild: VNode,
+  wrapperCache: Map<string, Component>,
+  fallback: unknown,
+): VNode | null {
+  const matchProps = activeChild.props as {
+    segment?: string;
+    keepAlive?: boolean;
+  } | null;
+
+  if (matchProps?.keepAlive === true && activeChild.type === Match) {
+    /* v8 ignore start */
+    const segment = matchProps.segment ?? "__not-found__";
+    /* v8 ignore stop */
+    const WrapperComponent = getOrCreateWrapper(wrapperCache, segment);
+    const slotContent = getSlotContent(activeChild) ?? [];
+
+    return h(Fragment, [
+      h(KeepAlive, null, {
+        default: () =>
+          h(WrapperComponent, { key: segment }, { default: () => slotContent }),
+      }),
+    ]);
+  }
+
+  const content = getSlotContent(activeChild);
+
+  /* v8 ignore start */
+  if (!content) {
+    return null;
+  }
+  /* v8 ignore stop */
+
+  return h(Fragment, [
+    h(KeepAlive, null, { default: () => h(emptyKeepAlivePlaceholder) }),
+    wrapWithSuspense(h(Fragment, content), fallback),
+  ]);
+}
+
+const RouteViewComponent = defineComponent({
+  name: "RouteView",
+  props: {
+    nodeName: {
+      type: String,
+      required: true,
+    },
+    keepAlive: {
+      type: Boolean,
+      default: false,
+    },
+  },
+  setup(props, { slots }) {
+    const routeContext = useRouteNode(props.nodeName);
+    const wrapperCache = new Map<string, Component>();
+
+    return (): VNode | null => {
+      const route = routeContext.route.value;
+
+      if (!route) {
+        return null;
+      }
+
+      const elements: VNode[] = [];
+
+      collectElements(slots.default?.(), elements);
+
+      const { rendered, fallback } = buildRenderList(
+        elements,
+        route.name,
+        props.nodeName,
+      );
+
+      if (rendered.length === 0) {
+        return null;
+      }
+
+      const activeChild = rendered[0];
+
+      if (props.keepAlive) {
+        return renderWithRootKA(activeChild, wrapperCache, fallback);
+      }
+
+      /* v8 ignore start */
+      if (activeChild.type !== Match && activeChild.type !== NotFound) {
+        return null;
+      }
+      /* v8 ignore stop */
+
+      const hasPerMatchKA = elements.some(
+        (element) =>
+          element.type === Match &&
+          (element.props as { keepAlive?: boolean } | null)?.keepAlive === true,
+      );
+
+      if (hasPerMatchKA) {
+        return renderWithPerMatchKA(activeChild, wrapperCache, fallback);
+      }
+
+      const content = getSlotContent(activeChild);
+
+      if (!content) {
+        return null;
+      }
+
+      return wrapWithSuspense(h(Fragment, content), fallback);
+    };
+  },
+});
+
+export const RouteView = Object.assign(RouteViewComponent, { Match, NotFound });
+
+export type {
+  RouteViewProps,
+  MatchProps as RouteViewMatchProps,
+  NotFoundProps as RouteViewNotFoundProps,
+} from "./types";

package/src/components/RouteView/components.ts

@@ -0,0 +1,35 @@
+import { defineComponent } from "vue";
+
+import type { PropType, VNode } from "vue";
+
+function renderNull() {
+  return null;
+}
+
+export const Match = defineComponent({
+  name: "RouteView.Match",
+  props: {
+    segment: {
+      type: String as PropType<string>,
+      required: true,
+    },
+    exact: {
+      type: Boolean,
+      default: false,
+    },
+    fallback: {
+      type: [Object, Function] as PropType<VNode | (() => VNode)>,
+      default: undefined,
+    },
+    keepAlive: {
+      type: Boolean,
+      default: false,
+    },
+  },
+  render: renderNull,
+});
+
+export const NotFound = defineComponent({
+  name: "RouteView.NotFound",
+  render: renderNull,
+});

package/src/components/RouteView/helpers.ts

@@ -0,0 +1,110 @@
+import { UNKNOWN_ROUTE } from "@real-router/core";
+import { startsWithSegment } from "@real-router/route-utils";
+import { Fragment, isVNode } from "vue";
+
+import { Match, NotFound } from "./components";
+
+import type { VNode } from "vue";
+
+type FallbackType = VNode | (() => VNode) | undefined;
+
+function isSegmentMatch(
+  routeName: string,
+  fullSegmentName: string,
+  exact: boolean,
+): boolean {
+  if (exact) {
+    return routeName === fullSegmentName;
+  }
+
+  return startsWithSegment(routeName, fullSegmentName);
+}
+
+function normalizeChildren(children: unknown): VNode[] {
+  if (Array.isArray(children)) {
+    const result: VNode[] = [];
+
+    for (const child of children) {
+      if (Array.isArray(child)) {
+        result.push(...normalizeChildren(child));
+      } else if (isVNode(child)) {
+        result.push(child);
+      }
+    }
+
+    return result;
+  }
+
+  if (isVNode(children)) {
+    return [children];
+  }
+
+  return [];
+}
+
+export function collectElements(children: unknown, result: VNode[]): void {
+  const vnodes = normalizeChildren(children);
+
+  for (const child of vnodes) {
+    if (child.type === Match || child.type === NotFound) {
+      result.push(child);
+    } else if (child.type === Fragment) {
+      collectElements(child.children, result);
+    }
+  }
+}
+
+export function buildRenderList(
+  elements: VNode[],
+  routeName: string,
+  nodeName: string,
+): {
+  rendered: VNode[];
+  activeMatchFound: boolean;
+  fallback?: FallbackType;
+} {
+  let notFoundChildren: unknown = null;
+  let activeMatchFound = false;
+  let fallback: FallbackType = undefined;
+  const rendered: VNode[] = [];
+
+  for (const child of elements) {
+    if (child.type === NotFound) {
+      notFoundChildren = child.children;
+      continue;
+    }
+
+    const props = child.props as {
+      segment: string;
+      exact?: boolean;
+      fallback?: FallbackType;
+    } | null;
+    const segment = props?.segment ?? "";
+    const exact = props?.exact ?? false;
+    const fullSegmentName = nodeName ? `${nodeName}.${segment}` : segment;
+    const isActive =
+      !activeMatchFound && isSegmentMatch(routeName, fullSegmentName, exact);
+
+    if (isActive) {
+      activeMatchFound = true;
+      fallback = props?.fallback;
+      rendered.push(child);
+    }
+  }
+
+  if (
+    !activeMatchFound &&
+    routeName === UNKNOWN_ROUTE &&
+    notFoundChildren !== null
+  ) {
+    const nfElements = elements.filter((element) => element.type === NotFound);
+    /* v8 ignore next 3 */
+    const lastNf = nfElements.at(-1);
+
+    if (lastNf) {
+      rendered.push(lastNf);
+    }
+  }
+
+  return { rendered, activeMatchFound, fallback };
+}

package/src/components/RouteView/index.ts

@@ -0,0 +1,7 @@
+export { RouteView } from "./RouteView";
+
+export type {
+  RouteViewProps,
+  RouteViewMatchProps,
+  RouteViewNotFoundProps,
+} from "./RouteView";

package/src/components/RouteView/types.ts

@@ -0,0 +1,15 @@
+import type { VNode } from "vue";
+
+export interface RouteViewProps {
+  readonly nodeName: string;
+  readonly keepAlive?: boolean;
+}
+
+export interface MatchProps {
+  readonly segment: string;
+  readonly exact?: boolean;
+  readonly fallback?: VNode | (() => VNode);
+  readonly keepAlive?: boolean;
+}
+
+export type NotFoundProps = Record<string, never>;

package/src/components/RouterErrorBoundary.ts

@@ -0,0 +1,69 @@
+import { defineComponent, h, ref, watch, computed, Fragment } from "vue";
+
+import { useRouterError } from "../composables/useRouterError";
+
+import type { RouterError, State } from "@real-router/core";
+import type { VNode, PropType } from "vue";
+
+export const RouterErrorBoundary = defineComponent({
+  name: "RouterErrorBoundary",
+  props: {
+    fallback: {
+      type: Function as PropType<
+        (error: RouterError, resetError: () => void) => VNode
+      >,
+      required: true,
+    },
+    onError: {
+      type: Function as PropType<
+        (
+          error: RouterError,
+          toRoute: State | null,
+          fromRoute: State | null,
+        ) => void
+      >,
+      default: undefined,
+    },
+  },
+  setup(props, { slots }) {
+    const snapshot = useRouterError();
+    const dismissedVersion = ref(-1);
+
+    watch(
+      () => snapshot.value.version,
+      () => {
+        if (snapshot.value.error) {
+          props.onError?.(
+            snapshot.value.error,
+            snapshot.value.toRoute,
+            snapshot.value.fromRoute,
+          );
+        }
+      },
+      { immediate: true },
+    );
+
+    const visibleError = computed(() =>
+      snapshot.value.version > dismissedVersion.value
+        ? snapshot.value.error
+        : null,
+    );
+
+    const resetError = () => {
+      dismissedVersion.value = snapshot.value.version;
+    };
+
+    return () => {
+      const children = slots.default?.() ?? [];
+      const errorVNode = visibleError.value
+        ? props.fallback(visibleError.value, resetError)
+        : null;
+
+      return h(Fragment, null, [...children, errorVNode]);
+    };
+  },
+});
+
+export type RouterErrorBoundaryProps = InstanceType<
+  typeof RouterErrorBoundary
+>["$props"];

package/src/composables/useIsActiveRoute.ts

@@ -0,0 +1,23 @@
+import { createActiveRouteSource } from "@real-router/sources";
+
+import { useRefFromSource } from "../useRefFromSource";
+import { useRouter } from "./useRouter";
+
+import type { Params } from "@real-router/core";
+import type { ShallowRef } from "vue";
+
+export function useIsActiveRoute(
+  routeName: string,
+  params?: Params,
+  strict = false,
+  ignoreQueryParams = true,
+): ShallowRef<boolean> {
+  const router = useRouter();
+
+  const source = createActiveRouteSource(router, routeName, params, {
+    strict,
+    ignoreQueryParams,
+  });
+
+  return useRefFromSource(source);
+}

package/src/composables/useNavigator.ts

@@ -0,0 +1,15 @@
+import { inject } from "vue";
+
+import { NavigatorKey } from "../context";
+
+import type { Navigator } from "@real-router/core";
+
+export const useNavigator = (): Navigator => {
+  const navigator = inject(NavigatorKey);
+
+  if (!navigator) {
+    throw new Error("useNavigator must be used within a RouterProvider");
+  }
+
+  return navigator;
+};

package/src/composables/useRoute.ts

@@ -0,0 +1,15 @@
+import { inject } from "vue";
+
+import { RouteKey } from "../context";
+
+import type { RouteContext } from "../types";
+
+export const useRoute = (): RouteContext => {
+  const routeContext = inject(RouteKey);
+
+  if (!routeContext) {
+    throw new Error("useRoute must be used within a RouterProvider");
+  }
+
+  return routeContext;
+};

package/src/composables/useRouteNode.ts

@@ -0,0 +1,38 @@
+import { getNavigator } from "@real-router/core";
+import { createRouteNodeSource } from "@real-router/sources";
+import { shallowRef, watch } from "vue";
+
+import { useRefFromSource } from "../useRefFromSource";
+import { useRouter } from "./useRouter";
+
+import type { RouteContext } from "../types";
+import type { State } from "@real-router/core";
+
+export function useRouteNode(nodeName: string): RouteContext {
+  const router = useRouter();
+
+  const source = createRouteNodeSource(router, nodeName);
+  const snapshot = useRefFromSource(source);
+
+  const navigator = getNavigator(router);
+
+  const route = shallowRef<State | undefined>(snapshot.value.route);
+  const previousRoute = shallowRef<State | undefined>(
+    snapshot.value.previousRoute,
+  );
+
+  watch(
+    snapshot,
+    (newSnapshot) => {
+      route.value = newSnapshot.route;
+      previousRoute.value = newSnapshot.previousRoute;
+    },
+    { flush: "sync" },
+  );
+
+  return {
+    navigator,
+    route,
+    previousRoute,
+  };
+}

package/src/composables/useRouteUtils.ts

@@ -0,0 +1,12 @@
+import { getPluginApi } from "@real-router/core/api";
+import { getRouteUtils } from "@real-router/route-utils";
+
+import { useRouter } from "./useRouter";
+
+import type { RouteUtils } from "@real-router/route-utils";
+
+export const useRouteUtils = (): RouteUtils => {
+  const router = useRouter();
+
+  return getRouteUtils(getPluginApi(router).getTree());
+};

package/src/composables/useRouter.ts

@@ -0,0 +1,15 @@
+import { inject } from "vue";
+
+import { RouterKey } from "../context";
+
+import type { Router } from "@real-router/core";
+
+export const useRouter = (): Router => {
+  const router = inject(RouterKey);
+
+  if (!router) {
+    throw new Error("useRouter must be used within a RouterProvider");
+  }
+
+  return router;
+};

package/src/composables/useRouterError.ts

@@ -0,0 +1,23 @@
+import { createErrorSource } from "@real-router/sources";
+
+import { useRefFromSource } from "../useRefFromSource";
+import { useRouter } from "./useRouter";
+
+import type { Router } from "@real-router/core";
+import type { RouterErrorSnapshot, RouterSource } from "@real-router/sources";
+import type { ShallowRef } from "vue";
+
+const cache = new WeakMap<Router, RouterSource<RouterErrorSnapshot>>();
+
+export function useRouterError(): ShallowRef<RouterErrorSnapshot> {
+  const router = useRouter();
+
+  let source = cache.get(router);
+
+  if (!source) {
+    source = createErrorSource(router);
+    cache.set(router, source);
+  }
+
+  return useRefFromSource(source);
+}

package/src/composables/useRouterTransition.ts

@@ -0,0 +1,15 @@
+import { createTransitionSource } from "@real-router/sources";
+
+import { useRefFromSource } from "../useRefFromSource";
+import { useRouter } from "./useRouter";
+
+import type { RouterTransitionSnapshot } from "@real-router/sources";
+import type { ShallowRef } from "vue";
+
+export function useRouterTransition(): ShallowRef<RouterTransitionSnapshot> {
+  const router = useRouter();
+
+  const source = createTransitionSource(router);
+
+  return useRefFromSource(source);
+}

package/src/constants.ts

@@ -0,0 +1,9 @@
+/**
+ * Stable empty object for default params
+ */
+export const EMPTY_PARAMS = Object.freeze({});
+
+/**
+ * Stable empty options object
+ */
+export const EMPTY_OPTIONS = Object.freeze({});

package/src/context.ts

@@ -0,0 +1,9 @@
+import type { RouteContext as RouteContextType } from "./types";
+import type { Router, Navigator } from "@real-router/core";
+import type { InjectionKey } from "vue";
+
+export const RouterKey: InjectionKey<Router> = Symbol("RouterKey");
+
+export const NavigatorKey: InjectionKey<Navigator> = Symbol("NavigatorKey");
+
+export const RouteKey: InjectionKey<RouteContextType> = Symbol("RouteKey");

package/src/createRouterPlugin.ts

@@ -0,0 +1,36 @@
+import { getNavigator } from "@real-router/core";
+import { createRouteSource } from "@real-router/sources";
+import { shallowRef } from "vue";
+
+import { NavigatorKey, RouteKey, RouterKey } from "./context";
+import { setDirectiveRouter } from "./directives/vLink";
+
+import type { Router } from "@real-router/core";
+import type { Plugin } from "vue";
+
+export function createRouterPlugin(router: Router): Plugin<[]> {
+  return {
+    install(app): void {
+      const navigator = getNavigator(router);
+
+      setDirectiveRouter(router);
+
+      const source = createRouteSource(router);
+      const initialSnapshot = source.getSnapshot();
+
+      const route = shallowRef(initialSnapshot.route);
+      const previousRoute = shallowRef(initialSnapshot.previousRoute);
+
+      source.subscribe(() => {
+        const snapshot = source.getSnapshot();
+
+        route.value = snapshot.route;
+        previousRoute.value = snapshot.previousRoute;
+      });
+
+      app.provide(RouterKey, router);
+      app.provide(NavigatorKey, navigator);
+      app.provide(RouteKey, { navigator, route, previousRoute });
+    },
+  };
+}

package/src/directives/vLink.ts

@@ -0,0 +1,116 @@
+import { shouldNavigate, applyLinkA11y } from "dom-utils";
+
+import type { Router, NavigationOptions, Params } from "@real-router/core";
+import type { Directive } from "vue";
+
+export interface LinkDirectiveValue {
+  name: string;
+  params?: Params;
+  options?: NavigationOptions;
+}
+
+let _router: Router | null = null;
+
+export function setDirectiveRouter(router: Router): void {
+  _router = router;
+}
+
+export function getDirectiveRouter(): Router {
+  if (!_router) {
+    /* v8 ignore next 3 -- @preserve Defensive: router always initialized by RouterProvider */
+    throw new Error(
+      "v-link directive requires a RouterProvider ancestor. Make sure RouterProvider is mounted.",
+    );
+  }
+
+  return _router;
+}
+
+const clickHandlers = new WeakMap<HTMLElement, (evt: MouseEvent) => void>();
+const keydownHandlers = new WeakMap<
+  HTMLElement,
+  (evt: KeyboardEvent) => void
+>();
+
+function createClickHandler(
+  router: Router,
+  value: LinkDirectiveValue,
+): (evt: MouseEvent) => void {
+  return (evt: MouseEvent) => {
+    if (!shouldNavigate(evt)) {
+      return;
+    }
+
+    evt.preventDefault();
+    router
+      .navigate(value.name, value.params ?? {}, value.options ?? {})
+      .catch(() => {});
+  };
+}
+
+function createKeydownHandler(
+  router: Router,
+  value: LinkDirectiveValue,
+  element: HTMLElement,
+): (evt: KeyboardEvent) => void {
+  return (evt: KeyboardEvent) => {
+    if (evt.key === "Enter" && !(element instanceof HTMLButtonElement)) {
+      router
+        .navigate(value.name, value.params ?? {}, value.options ?? {})
+        .catch(() => {});
+    }
+  };
+}
+
+function attachHandlers(
+  element: HTMLElement,
+  router: Router,
+  value: LinkDirectiveValue,
+): void {
+  const handleClick = createClickHandler(router, value);
+  const handleKeyDown = createKeydownHandler(router, value, element);
+
+  element.addEventListener("click", handleClick);
+  element.addEventListener("keydown", handleKeyDown);
+
+  clickHandlers.set(element, handleClick);
+  keydownHandlers.set(element, handleKeyDown);
+}
+
+function detachHandlers(element: HTMLElement): void {
+  const clickHandler = clickHandlers.get(element);
+  const keydownHandler = keydownHandlers.get(element);
+
+  if (clickHandler) {
+    element.removeEventListener("click", clickHandler);
+  }
+  if (keydownHandler) {
+    element.removeEventListener("keydown", keydownHandler);
+  }
+
+  clickHandlers.delete(element);
+  keydownHandlers.delete(element);
+}
+
+export const vLink: Directive<HTMLElement, LinkDirectiveValue> = {
+  mounted(element, binding) {
+    const router = getDirectiveRouter();
+
+    applyLinkA11y(element);
+
+    element.style.cursor = "pointer";
+
+    attachHandlers(element, router, binding.value);
+  },
+
+  updated(element, binding) {
+    const router = getDirectiveRouter();
+
+    detachHandlers(element);
+    attachHandlers(element, router, binding.value);
+  },
+
+  beforeUnmount(element) {
+    detachHandlers(element);
+  },
+};

package/src/index.ts

@@ -0,0 +1,47 @@
+// Components
+export { RouteView } from "./components/RouteView";
+
+export { Link } from "./components/Link";
+
+export { RouterErrorBoundary } from "./components/RouterErrorBoundary";
+
+// Directives
+export { vLink } from "./directives/vLink";
+
+// Composables
+export { useRouter } from "./composables/useRouter";
+
+export { useNavigator } from "./composables/useNavigator";
+
+export { useRouteUtils } from "./composables/useRouteUtils";
+
+export { useRoute } from "./composables/useRoute";
+
+export { useRouteNode } from "./composables/useRouteNode";
+
+export { useRouterTransition } from "./composables/useRouterTransition";
+
+// Plugin
+export { createRouterPlugin } from "./createRouterPlugin";
+
+// Context
+export { RouterProvider } from "./RouterProvider";
+
+export { RouterKey, NavigatorKey, RouteKey } from "./context";
+
+// Types
+export type { LinkProps } from "./types";
+
+export type { RouterErrorBoundaryProps } from "./components/RouterErrorBoundary";
+
+export type { LinkDirectiveValue } from "./directives/vLink";
+
+export type {
+  RouteViewProps,
+  RouteViewMatchProps,
+  RouteViewNotFoundProps,
+} from "./components/RouteView";
+
+export type { Navigator } from "@real-router/core";
+
+export type { RouterTransitionSnapshot } from "@real-router/sources";

package/src/types.ts

@@ -0,0 +1,24 @@
+import type {
+  NavigationOptions,
+  Params,
+  Navigator,
+  State,
+} from "@real-router/core";
+import type { ShallowRef } from "vue";
+
+export interface RouteContext {
+  navigator: Navigator;
+  route: ShallowRef<State | undefined>;
+  previousRoute: ShallowRef<State | undefined>;
+}
+
+export interface LinkProps<P extends Params = Params> {
+  routeName: string;
+  routeParams?: P;
+  routeOptions?: NavigationOptions;
+  class?: string;
+  activeClassName?: string;
+  activeStrict?: boolean;
+  ignoreQueryParams?: boolean;
+  target?: string;
+}

package/src/useRefFromSource.ts

@@ -0,0 +1,16 @@
+import { shallowRef, onScopeDispose } from "vue";
+
+import type { RouterSource } from "@real-router/sources";
+import type { ShallowRef } from "vue";
+
+export function useRefFromSource<T>(source: RouterSource<T>): ShallowRef<T> {
+  const ref = shallowRef(source.getSnapshot());
+
+  const unsub = source.subscribe(() => {
+    ref.value = source.getSnapshot();
+  });
+
+  onScopeDispose(unsub);
+
+  return ref;
+}