@real-router/vue 0.15.2 → 0.15.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/vue",
-  "version": "0.15.2",
+  "version": "0.15.4",
   "type": "commonjs",
   "description": "Vue 3 integration for Real-Router",
   "main": "./dist/cjs/index.js",
@@ -34,8 +34,7 @@
     }
   },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "homepage": "https://github.com/greydragon888/real-router",
   "repository": {
@@ -66,15 +65,15 @@
   "license": "MIT",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.56.0",
-    "@real-router/sources": "^0.8.5",
-    "@real-router/route-utils": "^0.2.3"
+    "@real-router/route-utils": "^0.2.3",
+    "@real-router/sources": "^0.8.7",
+    "@real-router/core": "^0.58.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "6.9.1",
     "@vue/test-utils": "2.4.11",
-    "vue": "3.5.35",
-    "@real-router/browser-plugin": "^0.17.6"
+    "vue": "3.5.38",
+    "@real-router/browser-plugin": "^0.17.8"
   },
   "peerDependencies": {
     "vue": ">=3.3.0"

package/src/RouterProvider.ts

@@ -1,162 +0,0 @@
-import { defineComponent, onScopeDispose, provide, watch } from "vue";
-
-import { NavigatorKey, RouteKey, RouterKey } from "./context";
-import { pushDirectiveRouter } from "./directives/vLink";
-import {
-  createRouteAnnouncer,
-  createScrollRestoration,
-  createScrollSpy,
-  createViewTransitions,
-} from "./dom-utils";
-import { setupRouteProvision } from "./setupRouteProvision";
-
-import type { ScrollRestorationOptions, ScrollSpyOptions } from "./dom-utils";
-import type { Router } from "@real-router/core";
-import type { PropType } from "vue";
-
-interface Disposable {
-  destroy: () => void;
-}
-
-/**
- * Watch a dependency tuple and (re)create a toggleable utility (announcer /
- * scroll-restorer / view-transitions). The factory returns `undefined` to
- * mean "feature disabled" — no utility is created and no cleanup is wired.
- * When a utility IS returned, its `destroy()` is registered via `onCleanup`,
- * so flipping any dep (incl. the feature flag) tears down the previous
- * instance before constructing the next.
- *
- * Extracted from three near-identical `watch(... { immediate: true })` blocks
- * (announceNavigation / scrollRestoration / viewTransitions) — DRY without
- * losing the per-utility dep tuple shape.
- */
-function watchToggleableUtility<D extends readonly unknown[]>(
-  deps: () => D,
-  factory: (current: D) => Disposable | undefined,
-): void {
-  watch(
-    deps,
-    (current, _prev, onCleanup) => {
-      const utility = factory(current);
-
-      if (utility) {
-        onCleanup(() => {
-          utility.destroy();
-        });
-      }
-    },
-    { immediate: true },
-  );
-}
-
-export const RouterProvider = defineComponent({
-  name: "RouterProvider",
-  props: {
-    router: {
-      type: Object as PropType<Router>,
-      required: true,
-    },
-    announceNavigation: {
-      type: Boolean,
-      default: false,
-    },
-    scrollRestoration: {
-      type: Object as PropType<ScrollRestorationOptions>,
-    },
-    scrollSpy: {
-      type: Object as PropType<ScrollSpyOptions>,
-    },
-    viewTransitions: {
-      type: Boolean,
-      default: false,
-    },
-  },
-  setup(props, { slots }) {
-    // Reactive announceNavigation: setting prop true/false at runtime
-    // creates/destroys the announcer accordingly. Prior implementation read
-    // the prop only inside onMounted, so toggling it post-mount silently no-op'd.
-    watchToggleableUtility(
-      () => [props.router, props.announceNavigation] as const,
-      ([router, enabled]) =>
-        enabled ? createRouteAnnouncer(router) : undefined,
-    );
-
-    // Watch by primitives so inline `{ mode: "restore" }` doesn't thrash.
-    // scrollContainer is a getter invoked lazily on every event inside the
-    // utility — swapping its reference doesn't change the resolved element,
-    // so we intentionally omit it from watched sources.
-    watchToggleableUtility(
-      () =>
-        [
-          props.router,
-          props.scrollRestoration !== undefined,
-          props.scrollRestoration?.mode,
-          props.scrollRestoration?.anchorScrolling,
-          props.scrollRestoration?.behavior,
-          props.scrollRestoration?.storageKey,
-        ] as const,
-      ([router, enabled, mode, anchorScrolling, behavior, storageKey]) => {
-        if (!enabled) {
-          return;
-        }
-
-        return createScrollRestoration(router, {
-          mode,
-          anchorScrolling,
-          behavior,
-          storageKey,
-          scrollContainer: props.scrollRestoration?.scrollContainer,
-        });
-      },
-    );
-
-    // Reactive scrollSpy: watch by primitives, omit scrollContainer getter
-    // identity for the same reason scrollRestoration does.
-    watchToggleableUtility(
-      () =>
-        [
-          props.router,
-          props.scrollSpy !== undefined && props.scrollSpy.selector !== "",
-          props.scrollSpy?.selector,
-          props.scrollSpy?.rootMargin,
-        ] as const,
-      ([router, enabled, selector, rootMargin]) => {
-        if (!enabled || !selector) {
-          return;
-        }
-
-        return createScrollSpy(router, {
-          selector,
-          rootMargin,
-          scrollContainer: props.scrollSpy?.scrollContainer,
-        });
-      },
-    );
-
-    // Reactive viewTransitions: toggling prop creates/destroys the utility.
-    watchToggleableUtility(
-      () => [props.router, props.viewTransitions] as const,
-      ([router, enabled]) =>
-        enabled ? createViewTransitions(router) : undefined,
-    );
-
-    // Push this provider's router on the v-link directive stack so nested
-    // RouterProviders behave like nested DI scopes (LIFO). Release on unmount
-    // restores the outer router for any v-link still mounted in the parent.
-    const releaseDirective = pushDirectiveRouter(props.router);
-
-    const { navigator, route, previousRoute, unsubscribe } =
-      setupRouteProvision(props.router);
-
-    onScopeDispose(() => {
-      releaseDirective();
-      unsubscribe();
-    });
-
-    provide(RouterKey, props.router);
-    provide(NavigatorKey, navigator);
-    provide(RouteKey, { navigator, route, previousRoute });
-
-    return () => slots.default?.();
-  },
-});

package/src/components/Await.ts

@@ -1,47 +0,0 @@
-import { defineComponent } from "vue";
-
-import { useDeferred } from "../composables/useDeferred";
-
-/**
- * Reads `useDeferred(name)` and hands the resolved value to the `default`
- * scoped slot via Vue's native `async setup()` Suspense pattern. Wrap in
- * `<Streamed>` (or Vue's `<Suspense>`).
- *
- * ```vue-html
- * <Streamed>
- *   <Await name="reviews" v-slot="{ value }">
- *     <ReviewList :items="value" />
- *   </Await>
- *   <template #fallback>
- *     <Spinner />
- *   </template>
- * </Streamed>
- * ```
- *
- * Or with the render function:
- *
- * ```ts
- * h(Await, { name: "reviews" }, {
- *   default: ({ value }: { value: Review[] }) => h(ReviewList, { items: value }),
- * });
- * ```
- *
- * Implementation: `async setup()` awaits the deferred promise. Vue's
- * `<Suspense>` boundary catches the pending promise and shows the fallback
- * until resolution. Rejection bubbles to the nearest `onErrorCaptured`
- * handler.
- */
-export const Await = defineComponent({
-  name: "Await",
-  props: {
-    /** Deferred key declared in the loader's `defer({ deferred: { <name>: ... } })`. */
-    name: { type: String, required: true },
-  },
-  async setup(props, { slots }) {
-    const value = await useDeferred(props.name);
-
-    return () => slots.default?.({ value });
-  },
-});
-
-export type AwaitProps = InstanceType<typeof Await>["$props"];

package/src/components/ClientOnly.ts

@@ -1,16 +0,0 @@
-import { defineComponent, onMounted, ref } from "vue";
-
-export const ClientOnly = defineComponent({
-  name: "ClientOnly",
-  setup(_, { slots }) {
-    const mounted = ref(false);
-
-    onMounted(() => {
-      mounted.value = true;
-    });
-
-    return () => (mounted.value ? slots.default?.() : slots.fallback?.());
-  },
-});
-
-export type ClientOnlyProps = InstanceType<typeof ClientOnly>["$props"];

package/src/components/HttpStatusCode.ts

@@ -1,74 +0,0 @@
-import { defineComponent, inject } from "vue";
-
-import { HTTP_STATUS_KEY } from "../context";
-
-// Module-scope render function — returns null since the component emits no DOM.
-// Hoisted to satisfy `unicorn/consistent-function-scoping` and to avoid
-// re-creating the closure on every component instantiation.
-const renderNull = (): null => null;
-
-/**
- * Render-time HTTP status declaration. Mount inside a route component (typical
- * use case: a glob `*` route's NotFound page) when the status is decided by
- * the rendered tree rather than a loader.
- *
- * Writes `code` to the nearest `<HttpStatusProvider>`'s sink during `setup()`
- * and renders nothing. With no provider mounted (the standard client-side
- * case) the component is a silent no-op — same component tree hydrates
- * without touching the DOM or warning about mismatches.
- *
- * Loader-driven errors (`LoaderNotFound` → 404, `LoaderRedirect` → 30x) keep
- * working as before; this component covers render-time decisions only.
- *
- * Last write wins when several `<HttpStatusCode />` instances mount in the
- * same render pass — sink reflects the last component that ran.
- *
- * ```vue-html
- * <HttpStatusProvider :sink="sink">
- *   <RouterProvider :router="router">
- *     <App />
- *   </RouterProvider>
- * </HttpStatusProvider>
- *
- * <!-- inside NotFound.vue -->
- * <HttpStatusCode :code="404" />
- * ```
- *
- * **`renderToWebStream` (streaming SSR):** Vue 3 `<Suspense>` is
- * chunked-blocking — Vue waits for every `async setup()` inside a boundary
- * before emitting the chunks past it. So in practice `<HttpStatusCode />`
- * inside a `<Suspense>` boundary still writes to the sink before the
- * response headers flush. Still, prefer mounting in the shell to avoid
- * coupling the contract to that particular Vue 3 streaming behaviour. With
- * `renderToString` there is no ordering concern at all.
- *
- * **Hydration symmetry:** `<HttpStatusProvider>` wraps a render slot, so
- * Vue emits a fragment marker pair (`<!--[-->` / `<!--]-->`) around its
- * children server-side. Mount the same `<HttpStatusProvider>` on the
- * client (with a throwaway sink) to keep the marker count balanced — see
- * the `ssr/` example's `entry-client.ts`. Otherwise hydration logs
- * "Hydration completed but contains mismatches".
- *
- * **Valid `code` range:** Node's `res.end()` throws `Invalid status code`
- * on `NaN`, `0`, negative values, or values `> 999` — this surfaces as a
- * 5xx / dropped connection, not silent corruption. Pass a real HTTP status
- * integer (commonly 4xx/5xx; 100-999 is what Node accepts).
- */
-export const HttpStatusCode = defineComponent({
-  name: "HttpStatusCode",
-  props: {
-    /** HTTP status to apply to the response. Common values: 404, 410, 451, 503. */
-    code: { type: Number, required: true },
-  },
-  setup(props) {
-    const sink = inject(HTTP_STATUS_KEY, null);
-
-    if (sink) {
-      sink.code = props.code;
-    }
-
-    return renderNull;
-  },
-});
-
-export type HttpStatusCodeProps = InstanceType<typeof HttpStatusCode>["$props"];

package/src/components/HttpStatusProvider.ts

@@ -1,22 +0,0 @@
-import { defineComponent, provide } from "vue";
-
-import { HTTP_STATUS_KEY } from "../context";
-
-import type { HttpStatusSink } from "../utils/createHttpStatusSink";
-import type { PropType } from "vue";
-
-export const HttpStatusProvider = defineComponent({
-  name: "HttpStatusProvider",
-  props: {
-    sink: { type: Object as PropType<HttpStatusSink>, required: true },
-  },
-  setup(props, { slots }) {
-    provide(HTTP_STATUS_KEY, props.sink);
-
-    return () => slots.default?.();
-  },
-});
-
-export type HttpStatusProviderProps = InstanceType<
-  typeof HttpStatusProvider
->["$props"];

package/src/components/Link.ts

@@ -1,226 +0,0 @@
-import { canonicalJson, createActiveRouteSource } from "@real-router/sources";
-import { defineComponent, h, computed, shallowRef, watch } from "vue";
-
-import { useRouter } from "../composables/useRouter";
-import { EMPTY_PARAMS, EMPTY_OPTIONS } from "../constants";
-import {
-  shouldNavigate,
-  buildHref,
-  buildActiveClassName,
-  navigateWithHash,
-} from "../dom-utils";
-
-import type { Params, NavigationOptions } from "@real-router/core";
-import type { PropType } from "vue";
-
-type OnClickHandler = (evt: MouseEvent) => void;
-
-/**
- * Vue's compiled template binds multiple `@click` handlers as an array.
- * Single render-function `onClick` is a function. Both must be invoked.
- *
- * The function-branch deliberately omits a `defaultPrevented` check: the
- * single call short-circuits naturally and control returns to the caller
- * (`handleClick`), which then re-reads `evt.defaultPrevented` on the same
- * MouseEvent. The array-branch needs the per-iteration check because the
- * caller cannot observe intermediate handlers — without it, later handlers
- * would still run after an earlier one called `preventDefault()`.
- */
-function invokeAttributesOnClick(value: unknown, evt: MouseEvent): void {
-  if (typeof value === "function") {
-    (value as OnClickHandler)(evt);
-
-    return;
-  }
-  if (Array.isArray(value)) {
-    const handlers = value as OnClickHandler[];
-
-    for (const fn of handlers) {
-      if (typeof fn === "function") {
-        fn(evt);
-
-        if (evt.defaultPrevented) {
-          return;
-        }
-      }
-    }
-  }
-}
-
-export const Link = defineComponent({
-  name: "Link",
-  // Disable Vue's automatic attribute fallthrough. Without this, attrs.onClick
-  // (function OR array) is auto-attached as a native click listener AND our
-  // explicit onClick fires too — user handlers are double-invoked. We invoke
-  // attrs.onClick manually inside handleClick to preserve preventDefault.
-  inheritAttrs: false,
-  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,
-    },
-    /**
-     * URL fragment (decoded form, no leading "#") (#532).
-     * - omitted/`undefined` → preserve current fragment on same-route navigation
-     * - `""` → clear fragment
-     * - non-empty → set fragment
-     */
-    hash: {
-      type: String,
-      default: undefined,
-    },
-  },
-  setup(props, { slots, attrs }) {
-    const router = useRouter();
-
-    const isActive = shallowRef(false);
-
-    // watch with an explicit dep getter recreates the source ONLY when the
-    // structural identity of routeName/routeParams/strict/ignoreQueryParams/
-    // hash changes — not on every parent rerender that hands a fresh
-    // `routeParams` literal with the same shape.
-    //
-    // Hot-path note: inline `:routeParams="{ id: 1 }"` in a parent template
-    // allocates a new object each render. Comparing by reference would
-    // tear down + recreate the ActiveRouteSource subscription on every
-    // unrelated parent state change. `canonicalJson(routeParams)` collapses
-    // structurally-equal objects to the same key-order-stable string, so the
-    // subscription persists across re-renders that don't change shape.
-    // (The source's own per-router cache uses the same canonical key under
-    // the hood — this watch dep just mirrors it at the consumer layer.)
-    watch(
-      () =>
-        [
-          props.routeName,
-          canonicalJson(props.routeParams),
-          props.activeStrict,
-          props.ignoreQueryParams,
-          props.hash,
-        ] as const,
-      (
-        [routeName, _paramsKey, activeStrict, ignoreQueryParams, hash],
-        _prev,
-        onCleanup,
-      ) => {
-        // Re-read the raw `routeParams` ref when constructing the source —
-        // canonicalJson was only used for change-detection above, the source
-        // factory still wants the live object.
-        const routeParams = props.routeParams;
-        // Hash-aware active (#532): pass hash through so tab links with the
-        // same routeName but different `hash` props don't all light up.
-        const source = createActiveRouteSource(
-          router,
-          routeName,
-          routeParams,
-          hash === undefined
-            ? { strict: activeStrict, ignoreQueryParams }
-            : { strict: activeStrict, ignoreQueryParams, hash },
-        );
-
-        isActive.value = source.getSnapshot();
-
-        const unsub = source.subscribe(() => {
-          isActive.value = source.getSnapshot();
-        });
-
-        onCleanup(unsub);
-      },
-      { immediate: true, flush: "sync" },
-    );
-
-    const href = computed(() =>
-      buildHref(
-        router,
-        props.routeName,
-        props.routeParams,
-        props.hash === undefined ? undefined : { hash: props.hash },
-      ),
-    );
-
-    const finalClassName = computed(() =>
-      buildActiveClassName(isActive.value, props.activeClassName, props.class),
-    );
-
-    const handleClick = (evt: MouseEvent) => {
-      // Vue allows attrs.onClick to be a function or an array of functions
-      // (compiled templates with multiple @click bindings produce arrays).
-      // Both must be invoked; treating arrays as "no handler" silently drops
-      // user code.
-      if (attrs.onClick !== undefined && attrs.onClick !== null) {
-        invokeAttributesOnClick(attrs.onClick, evt);
-
-        if (evt.defaultPrevented) {
-          return;
-        }
-      }
-
-      if (!shouldNavigate(evt) || props.target === "_blank") {
-        return;
-      }
-
-      evt.preventDefault();
-      navigateWithHash(
-        router,
-        props.routeName,
-        props.routeParams,
-        props.hash,
-        props.routeOptions,
-      ).catch(() => {});
-    };
-
-    return () => {
-      // Build forwarded attrs without `onClick`. Vue's runtime auto-attaches
-      // attrs.onClick (function OR array) as a native DOM listener, which would
-      // double-invoke user handlers when combined with our explicit `onClick`.
-      // We invoke the original attrs.onClick manually inside handleClick so the
-      // preventDefault contract is preserved.
-      //
-      // Spread + delete avoids the per-key copy loop on every render — one
-      // allocation + one property deletion instead of N iterations across
-      // data-*, aria-*, role, etc. Hot-path optimisation for Link-heavy pages.
-      const restAttributes = { ...attrs };
-
-      delete restAttributes.onClick;
-
-      return h(
-        "a",
-        {
-          ...restAttributes,
-          href: href.value,
-          class: finalClassName.value,
-          target: props.target,
-          onClick: handleClick,
-        },
-        slots.default?.(),
-      );
-    };
-  },
-});