@real-router/navigation-plugin 0.0.1

package/src/plugin.ts

@@ -0,0 +1,298 @@
+import { UNKNOWN_ROUTE } from "@real-router/core";
+import {
+  shouldReplaceHistory,
+  buildUrl,
+  extractPath,
+  urlToPath,
+} from "browser-env";
+
+import { LOGGER_CONTEXT } from "./constants";
+import {
+  peekBack,
+  peekForward,
+  hasVisited,
+  getVisitedRoutes,
+  getRouteVisitCount,
+  findLastEntryForRoute,
+  canGoBack,
+  canGoForward,
+  canGoBackTo,
+} from "./history-extensions";
+import { createNavigateHandler } from "./navigate-handler";
+import {
+  createStartInterceptor,
+  createReplaceHistoryState,
+} from "./plugin-utils";
+
+import type {
+  NavigationBrowser,
+  NavigationMeta,
+  NavigationPluginOptions,
+  NavigationSharedState,
+} from "./types";
+import type {
+  NavigationOptions,
+  Params,
+  Router,
+  State,
+  Plugin,
+} from "@real-router/core";
+import type { PluginApi } from "@real-router/core/api";
+
+function deriveNavigationType(
+  navOptions: NavigationOptions,
+  toState: State,
+  fromState: State | undefined,
+): NavigationMeta["navigationType"] {
+  if (navOptions.reload && toState.path === fromState?.path) {
+    return "reload";
+  }
+
+  if (shouldReplaceHistory(navOptions, toState, fromState)) {
+    return "replace";
+  }
+
+  return "push";
+}
+
+export class NavigationPlugin {
+  readonly #router: Router;
+  readonly #api: PluginApi;
+  readonly #options: Required<NavigationPluginOptions>;
+  readonly #browser: NavigationBrowser;
+  readonly #removeStartInterceptor: () => void;
+  readonly #removeExtensions: () => void;
+  readonly #lifecycle: Pick<Plugin, "onStart" | "onStop" | "teardown">;
+
+  #isSyncingFromRouter = false;
+  readonly #metaByState = new WeakMap<State, NavigationMeta>();
+  #pendingMeta: NavigationMeta | undefined;
+  #pendingTraverseKey: string | undefined;
+
+  constructor(
+    router: Router,
+    api: PluginApi,
+    options: Required<NavigationPluginOptions>,
+    browser: NavigationBrowser,
+    transitionOptions: {
+      source: string;
+      replace: true;
+      forceDeactivate?: boolean;
+    },
+    shared: NavigationSharedState,
+  ) {
+    this.#router = router;
+    this.#api = api;
+    this.#options = options;
+    this.#browser = browser;
+
+    this.#removeStartInterceptor = createStartInterceptor(api, browser);
+
+    const pluginBuildUrl = (route: string, params?: Params) => {
+      const path = router.buildPath(route, params);
+
+      return buildUrl(path, options.base);
+    };
+
+    this.#removeExtensions = api.extendRouter({
+      buildUrl: pluginBuildUrl,
+      matchUrl: (url: string) => {
+        const path = urlToPath(url, options.base, LOGGER_CONTEXT);
+
+        return path ? api.matchPath(path) : undefined;
+      },
+      replaceHistoryState: createReplaceHistoryState(
+        api,
+        router,
+        browser,
+        pluginBuildUrl,
+        (syncing) => {
+          this.#isSyncingFromRouter = syncing;
+        },
+      ),
+
+      peekBack: () => peekBack(browser, api, options.base),
+      peekForward: () => peekForward(browser, api, options.base),
+      hasVisited: (routeName: string) =>
+        hasVisited(browser, api, options.base, routeName),
+      getVisitedRoutes: () => getVisitedRoutes(browser, api, options.base),
+      getRouteVisitCount: (routeName: string) =>
+        getRouteVisitCount(browser, api, options.base, routeName),
+      traverseToLast: (routeName: string) => this.traverseToLast(routeName),
+      getNavigationMeta: (state?: State): NavigationMeta | undefined => {
+        if (!state) {
+          return this.#pendingMeta;
+        }
+
+        return this.#metaByState.get(state);
+      },
+      canGoBack: () => canGoBack(browser),
+      canGoForward: () => canGoForward(browser),
+      canGoBackTo: (routeName: string) =>
+        canGoBackTo(browser, api, options.base, routeName),
+    });
+
+    const handler = createNavigateHandler({
+      router,
+      api,
+      browser,
+      isSyncingFromRouter: () => this.#isSyncingFromRouter,
+      setSyncing: (syncing) => {
+        this.#isSyncingFromRouter = syncing;
+      },
+      setPendingMeta: (meta) => {
+        this.#pendingMeta = meta;
+      },
+      base: options.base,
+      transitionOptions,
+    });
+
+    this.#lifecycle = createNavigateLifecycle({
+      browser,
+      shared,
+      handler,
+      removeStartInterceptor: this.#removeStartInterceptor,
+      removeExtensions: this.#removeExtensions,
+    });
+  }
+
+  async traverseToLast(routeName: string): Promise<State> {
+    const entries = this.#browser.entries();
+    const currentKey = this.#browser.currentEntry?.key;
+    const entry = findLastEntryForRoute(
+      entries,
+      routeName,
+      this.#api,
+      this.#options.base,
+      currentKey,
+    );
+
+    if (!entry) {
+      throw new Error(`No history entry for route "${routeName}"`);
+    }
+
+    if (!entry.url) {
+      throw new Error(`No matching route for entry URL "${entry.url}"`);
+    }
+
+    const parsedUrl = new URL(entry.url);
+    const path =
+      extractPath(parsedUrl.pathname, this.#options.base) + parsedUrl.search;
+    const matchedState = this.#api.matchPath(path);
+
+    if (!matchedState) {
+      throw new Error(`No matching route for entry URL "${entry.url}"`);
+    }
+
+    this.#pendingMeta = {
+      navigationType: "traverse",
+      userInitiated: false,
+    };
+    this.#pendingTraverseKey = entry.key;
+
+    return this.#router.navigate(matchedState.name, matchedState.params);
+  }
+
+  getPlugin(): Plugin {
+    return {
+      ...this.#lifecycle,
+
+      onTransitionSuccess: (
+        toState: State,
+        fromState: State | undefined,
+        navOptions: NavigationOptions,
+      ) => {
+        if (!this.#pendingMeta) {
+          this.#pendingMeta = {
+            navigationType: deriveNavigationType(
+              navOptions,
+              toState,
+              fromState,
+            ),
+            userInitiated: false,
+          };
+        }
+
+        this.#metaByState.set(toState, this.#pendingMeta);
+        this.#pendingMeta = undefined;
+
+        this.#isSyncingFromRouter = true;
+
+        if (this.#pendingTraverseKey) {
+          this.#browser.traverseTo(this.#pendingTraverseKey);
+          this.#pendingTraverseKey = undefined;
+        } else {
+          const url = this.#router.buildUrl(toState.name, toState.params);
+          const shouldPreserveHash =
+            !fromState || fromState.path === toState.path;
+          const finalUrl = shouldPreserveHash
+            ? url + this.#browser.getHash()
+            : url;
+          const historyState = {
+            name: toState.name,
+            params: toState.params,
+            path: toState.path,
+          };
+
+          if (toState.name === UNKNOWN_ROUTE) {
+            this.#browser.updateCurrentEntry({ state: historyState });
+          } else {
+            const replace = shouldReplaceHistory(
+              navOptions,
+              toState,
+              fromState,
+            );
+
+            this.#browser.navigate(finalUrl, {
+              state: historyState,
+              history: replace ? "replace" : "push",
+            });
+          }
+        }
+
+        this.#isSyncingFromRouter = false;
+      },
+
+      onTransitionCancel: () => {
+        this.#pendingMeta = undefined;
+        this.#pendingTraverseKey = undefined;
+      },
+
+      onTransitionError: () => {
+        this.#pendingMeta = undefined;
+        this.#pendingTraverseKey = undefined;
+      },
+    };
+  }
+}
+
+interface NavigateLifecycleDeps {
+  browser: NavigationBrowser;
+  handler: (event: NavigateEvent) => void;
+  removeStartInterceptor: () => void;
+  removeExtensions: () => void;
+  shared: NavigationSharedState;
+}
+
+function createNavigateLifecycle(deps: NavigateLifecycleDeps): Plugin {
+  return {
+    onStart() {
+      deps.shared.removeNavigateListener?.();
+      deps.shared.removeNavigateListener = deps.browser.addNavigateListener(
+        deps.handler,
+      );
+    },
+
+    onStop() {
+      deps.shared.removeNavigateListener?.();
+      deps.shared.removeNavigateListener = undefined;
+    },
+
+    teardown() {
+      deps.shared.removeNavigateListener?.();
+      deps.shared.removeNavigateListener = undefined;
+      deps.removeStartInterceptor();
+      deps.removeExtensions();
+    },
+  };
+}

package/src/ssr-fallback.ts

@@ -0,0 +1,47 @@
+import { createWarnOnce } from "browser-env";
+
+import type { NavigationBrowser } from "./types";
+
+const NOOP = (): void => {};
+
+export const createNavigationFallbackBrowser = (
+  context: string,
+): NavigationBrowser => {
+  const warnOnce = createWarnOnce(context);
+
+  return {
+    getLocation: () => {
+      warnOnce("getLocation");
+
+      return "/";
+    },
+    getHash: () => {
+      warnOnce("getHash");
+
+      return "";
+    },
+    navigate: () => {
+      warnOnce("navigate");
+    },
+    replaceState: () => {
+      warnOnce("replaceState");
+    },
+    updateCurrentEntry: () => {
+      warnOnce("updateCurrentEntry");
+    },
+    traverseTo: () => {
+      warnOnce("traverseTo");
+    },
+    addNavigateListener: () => {
+      warnOnce("addNavigateListener");
+
+      return NOOP;
+    },
+    entries: () => {
+      warnOnce("entries");
+
+      return [];
+    },
+    currentEntry: null,
+  };
+};

package/src/types.ts

@@ -0,0 +1,59 @@
+/**
+ * Navigation plugin configuration.
+ * Same options as browser-plugin — plugins are interchangeable.
+ */
+export interface NavigationPluginOptions {
+  /**
+   * Bypass canDeactivate guards on browser back/forward.
+   *
+   * @default true
+   */
+  forceDeactivate?: boolean;
+
+  /**
+   * Base path for all routes (e.g., "/app" for hosted at /app/).
+   *
+   * @default ""
+   */
+  base?: string;
+}
+
+/**
+ * Browser abstraction over Navigation API.
+ * Replaces History API's Browser interface with Navigation API equivalents.
+ */
+export interface NavigationBrowser {
+  getLocation: () => string;
+  getHash: () => string;
+  navigate: (
+    url: string,
+    options: { state: unknown; history: "push" | "replace" },
+  ) => void;
+  replaceState: (state: unknown, url: string) => void;
+  updateCurrentEntry: (options: { state: unknown }) => void;
+  traverseTo: (key: string) => void;
+  addNavigateListener: (fn: (evt: NavigateEvent) => void) => () => void;
+  entries: () => NavigationHistoryEntry[];
+  currentEntry: NavigationHistoryEntry | null;
+}
+
+/**
+ * Shared mutable state across plugin instances created by the same factory.
+ * Enables cleanup of a previous instance's navigate listener when the factory is reused.
+ */
+export interface NavigationSharedState {
+  removeNavigateListener: (() => void) | undefined;
+}
+
+/**
+ * Navigation metadata attached to State via WeakMap.
+ * Available in guards (via pendingMeta) and subscribe callbacks (via metaByState).
+ */
+export interface NavigationMeta {
+  /** Type of navigation: push, replace, traverse, or reload */
+  navigationType: "push" | "replace" | "traverse" | "reload";
+  /** Whether the navigation was initiated by the user (back/forward button, link click) */
+  userInitiated: boolean;
+  /** Ephemeral info passed via navigation.navigate({ info }) — lost on page reload */
+  info?: unknown;
+}

package/src/validation.ts

@@ -0,0 +1,10 @@
+import { createOptionsValidator } from "browser-env";
+
+import { LOGGER_CONTEXT, defaultOptions } from "./constants";
+
+import type { NavigationPluginOptions } from "./types";
+
+export const validateOptions = createOptionsValidator<NavigationPluginOptions>(
+  defaultOptions,
+  LOGGER_CONTEXT,
+);