@real-router/browser-plugin 0.11.5 → 0.11.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/browser-plugin",
-  "version": "0.11.5",
+  "version": "0.11.6",
   "type": "commonjs",
   "description": "Browser integration plugin with History API, hash routing, and popstate support",
   "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"
   ],
   "repository": {
     "type": "git",
@@ -44,7 +44,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.45.1"
+    "@real-router/core": "^0.45.2"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "6.9.1",
@@ -59,7 +59,7 @@
     "build": "tsdown --config-loader unrun",
     "type-check": "tsc --noEmit",
     "lint": "eslint --cache --ext .ts 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/constants.ts

@@ -0,0 +1,17 @@
+// packages/browser-plugin/modules/constants.ts
+
+import type { BrowserPluginOptions } from "./types";
+
+export const defaultOptions: Required<BrowserPluginOptions> = {
+  forceDeactivate: true,
+  base: "",
+};
+
+/**
+ * Source identifier for transitions triggered by browser events.
+ * Used to distinguish browser-initiated navigation (back/forward buttons)
+ * from programmatic navigation (router.navigate()).
+ */
+export const source = "popstate";
+
+export const LOGGER_CONTEXT = "browser-plugin";

package/src/factory.ts

@@ -0,0 +1,57 @@
+import { getPluginApi } from "@real-router/core/api";
+import {
+  createSafeBrowser,
+  normalizeBase,
+  safelyEncodePath,
+} from "browser-env";
+
+import { defaultOptions, source } from "./constants";
+import { BrowserPlugin } from "./plugin";
+import { extractPath } from "./url-utils";
+import { validateOptions } from "./validation";
+
+import type { BrowserPluginOptions } from "./types";
+import type { PluginFactory, Router } from "@real-router/core";
+import type { Browser, SharedFactoryState } from "browser-env";
+
+export function browserPluginFactory(
+  opts?: Partial<BrowserPluginOptions>,
+  browser?: Browser,
+): PluginFactory {
+  validateOptions(opts);
+
+  const options: Required<BrowserPluginOptions> = {
+    ...defaultOptions,
+    ...opts,
+  };
+
+  options.base = normalizeBase(options.base);
+
+  const resolvedBrowser =
+    browser ??
+    createSafeBrowser(
+      () =>
+        safelyEncodePath(
+          extractPath(globalThis.location.pathname, options.base),
+        ) + globalThis.location.search,
+      "browser-plugin",
+    );
+
+  const forceDeactivate = options.forceDeactivate;
+  const transitionOptions = { forceDeactivate, source, replace: true as const };
+
+  const shared: SharedFactoryState = { removePopStateListener: undefined };
+
+  return function browserPlugin(routerBase) {
+    const plugin = new BrowserPlugin(
+      routerBase as Router,
+      getPluginApi(routerBase),
+      options,
+      resolvedBrowser,
+      transitionOptions,
+      shared,
+    );
+
+    return plugin.getPlugin();
+  };
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+// packages/browser-plugin/modules/index.ts
+/* eslint-disable @typescript-eslint/method-signature-style -- method syntax required for declaration merging overload (property syntax causes TS2717) */
+// Public API exports for browser-plugin
+
+import type { Params, State } from "@real-router/core";
+
+// Main plugin factory
+export { browserPluginFactory } from "./factory";
+
+// Types
+export type { BrowserPluginOptions } from "./types";
+
+export type { Browser } from "browser-env";
+
+// Type guards
+export { isStateStrict as isState } from "type-guards";
+
+/**
+ * Module augmentation for real-router.
+ * Extends Router interface with browser plugin methods.
+ */
+declare module "@real-router/core" {
+  interface Router {
+    /**
+     * Builds full URL for a route with base path and hash prefix.
+     * Added by browser plugin.
+     */
+    buildUrl: (name: string, params?: Params) => string;
+
+    /**
+     * Matches URL and returns corresponding state.
+     * Added by browser plugin.
+     */
+    matchUrl: (url: string) => State | undefined;
+
+    /**
+     * Replaces current history state without triggering navigation.
+     * Added by browser plugin.
+     */
+    replaceHistoryState: (
+      name: string,
+      params?: Params,
+      title?: string,
+    ) => void;
+
+    start(path?: string): Promise<State>;
+  }
+}

package/src/plugin.ts

@@ -0,0 +1,118 @@
+import {
+  createPopstateHandler,
+  createPopstateLifecycle,
+  createStartInterceptor,
+  createReplaceHistoryState,
+  shouldReplaceHistory,
+  updateBrowserState,
+} from "browser-env";
+
+import { buildUrl, urlToPath } from "./url-utils";
+
+import type { BrowserPluginOptions } from "./types";
+import type {
+  NavigationOptions,
+  Params,
+  Router,
+  State,
+  Plugin,
+} from "@real-router/core";
+import type { PluginApi } from "@real-router/core/api";
+import type { Browser, SharedFactoryState } from "browser-env";
+
+export class BrowserPlugin {
+  readonly #router: Router;
+  readonly #browser: Browser;
+  readonly #removeStartInterceptor: () => void;
+  readonly #removeExtensions: () => void;
+  readonly #lifecycle: Pick<Plugin, "onStart" | "onStop" | "teardown">;
+
+  constructor(
+    router: Router,
+    api: PluginApi,
+    options: Required<BrowserPluginOptions>,
+    browser: Browser,
+    transitionOptions: {
+      source: string;
+      replace: true;
+      forceDeactivate?: boolean;
+    },
+    shared: SharedFactoryState,
+  ) {
+    this.#router = router;
+    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);
+
+        return path ? api.matchPath(path) : undefined;
+      },
+      replaceHistoryState: createReplaceHistoryState(
+        api,
+        router,
+        browser,
+        pluginBuildUrl,
+      ),
+    });
+
+    const handler = createPopstateHandler({
+      router,
+      api,
+      browser,
+      allowNotFound: api.getOptions().allowNotFound,
+      transitionOptions,
+      loggerContext: "browser-plugin",
+      buildUrl: (name: string, params?: Params) =>
+        router.buildUrl(name, params),
+    });
+
+    this.#lifecycle = createPopstateLifecycle({
+      browser,
+      shared,
+      handler,
+      cleanup: () => {
+        this.#removeStartInterceptor();
+        this.#removeExtensions();
+      },
+    });
+  }
+
+  getPlugin(): Plugin {
+    return {
+      ...this.#lifecycle,
+
+      onTransitionSuccess: (
+        toState: State,
+        fromState: State | undefined,
+        navOptions: NavigationOptions,
+      ) => {
+        const replaceHistory = shouldReplaceHistory(
+          navOptions,
+          toState,
+          fromState,
+        );
+
+        const url = this.#router.buildUrl(toState.name, toState.params);
+
+        const shouldPreserveHash =
+          !fromState || fromState.path === toState.path;
+
+        const finalUrl = shouldPreserveHash
+          ? url + this.#browser.getHash()
+          : url;
+
+        updateBrowserState(toState, finalUrl, replaceHistory, this.#browser);
+      },
+    };
+  }
+}

package/src/types.ts

@@ -0,0 +1,20 @@
+// packages/browser-plugin/src/types.ts
+
+/**
+ * Browser plugin configuration.
+ */
+export interface BrowserPluginOptions {
+  /**
+   * Force deactivation of current route even if canDeactivate returns false.
+   *
+   * @default true
+   */
+  forceDeactivate?: boolean;
+
+  /**
+   * Base path for all routes (e.g., "/app" for hosted at /app/).
+   *
+   * @default ""
+   */
+  base?: string;
+}

package/src/url-utils.ts

@@ -0,0 +1,27 @@
+// packages/browser-plugin/src/url-utils.ts
+
+import { safeParseUrl } from "browser-env";
+
+import { LOGGER_CONTEXT } from "./constants";
+
+export function extractPath(pathname: string, base: string): string {
+  if (base && pathname.startsWith(base)) {
+    const stripped = pathname.slice(base.length);
+
+    return stripped.startsWith("/") ? stripped : `/${stripped}`;
+  }
+
+  return pathname;
+}
+
+export function buildUrl(path: string, base: string): string {
+  return base + path;
+}
+
+export function urlToPath(url: string, base: string): string | null {
+  const parsedUrl = safeParseUrl(url, LOGGER_CONTEXT);
+
+  return parsedUrl
+    ? extractPath(parsedUrl.pathname, base) + parsedUrl.search
+    : null;
+}

package/src/validation.ts

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