feat(browser): implement navigate utility for SPA and cross-origin navigation

Author: brionmario

packages/browser/src/index.ts

@@ -46,6 +46,7 @@ export * from './__legacy__/worker/worker-receiver';
 export {AsgardeoBrowserConfig} from './models/config';
 
 export {default as hasAuthParamsInUrl} from './utils/hasAuthParamsInUrl';
+export {default as navigate} from './utils/navigate';
 
 export {default as AsgardeoBrowserClient} from './AsgardeoBrowserClient';
 

packages/browser/src/utils/__tests__/navigate.test.ts

@@ -0,0 +1,81 @@
+/**
+ * Copyright (c) 2025, WSO2 LLC. (https://www.wso2.com).
+ *
+ * WSO2 LLC. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import {vi} from 'vitest';
+import navigate from '../navigate';
+
+describe('navigate', () => {
+  const originalLocation = window.location;
+
+  beforeEach(() => {
+    // @ts-ignore
+    window.history.pushState = vi.fn();
+    // @ts-ignore
+    window.dispatchEvent = vi.fn();
+    // @ts-ignore
+    window.location.assign = vi.fn();
+    // @ts-ignore
+    delete window.location;
+    // @ts-ignore
+    window.location = {
+      ...originalLocation,
+      assign: vi.fn(),
+      origin: 'https://localhost:5173',
+      href: 'https://localhost:5173/',
+    };
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+    // @ts-ignore
+    window.location = originalLocation;
+  });
+
+  it('should call window.history.pushState with the correct arguments for same-origin', () => {
+    navigate('/test-url');
+    expect(window.history.pushState).toHaveBeenCalledWith(null, '', '/test-url');
+    expect(window.location.assign).not.toHaveBeenCalled();
+  });
+
+  it('should dispatch a PopStateEvent with state null for same-origin', () => {
+    navigate('/test-url');
+    expect(window.dispatchEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'popstate',
+        state: null,
+      }),
+    );
+    expect(window.location.assign).not.toHaveBeenCalled();
+  });
+
+  it('should use window.location.assign for cross-origin URLs', () => {
+    const crossOriginUrl = 'https://accounts.asgardeo.io/t/dxlab/accountrecoveryendpoint/register.do';
+    navigate(crossOriginUrl);
+    expect(window.location.assign).toHaveBeenCalledWith(crossOriginUrl);
+    expect(window.history.pushState).not.toHaveBeenCalled();
+    expect(window.dispatchEvent).not.toHaveBeenCalled();
+  });
+
+  it('should use window.location.assign for malformed URLs', () => {
+    const malformedUrl = 'http://[::1'; // Invalid URL
+    navigate(malformedUrl);
+    expect(window.location.assign).toHaveBeenCalledWith(malformedUrl);
+    expect(window.history.pushState).not.toHaveBeenCalled();
+    expect(window.dispatchEvent).not.toHaveBeenCalled();
+  });
+});

packages/browser/src/utils/navigate.ts

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) 2025, WSO2 LLC. (https://www.wso2.com).
+ *
+ * WSO2 LLC. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * Navigates to a new URL within the browser.
+ *
+ * - For same-origin URLs (relative paths or absolute URLs with the same origin),
+ *   uses the History API and dispatches a `popstate` event (SPA navigation).
+ * - For cross-origin URLs, performs a full page load using `window.location.assign`.
+ *
+ * This allows seamless navigation for both SPA routes and external links.
+ *
+ * @param url - The target URL to navigate to. Can be a path, query, or absolute URL.
+ *
+ * @example
+ * ```typescript
+ * // SPA navigation (same origin)
+ * navigate('/dashboard');
+ *
+ * // SPA navigation with query
+ * navigate('/search?q=asgardeo');
+ *
+ * // Cross-origin navigation (full page load)
+ * navigate('https://accounts.asgardeo.io/t/dxlab/accountrecoveryendpoint/register.do');
+ * ```
+ */
+const navigate = (url: string): void => {
+  try {
+    const targetUrl = new URL(url, window.location.origin);
+    if (targetUrl.origin === window.location.origin) {
+      window.history.pushState(null, '', targetUrl.pathname + targetUrl.search + targetUrl.hash);
+      window.dispatchEvent(new PopStateEvent('popstate', {state: null}));
+    } else {
+      window.location.assign(targetUrl.href);
+    }
+  } catch {
+    // If URL constructor fails (e.g., malformed URL), fallback to location.assign
+    window.location.assign(url);
+  }
+};
+
+export default navigate;

packages/browser/tsconfig.spec.json

@@ -3,11 +3,11 @@
   "compilerOptions": {
     "outDir": "dist",
     "module": "commonjs",
-    "types": ["jest", "node"]
+    "types": ["vitest/globals"]
   },
   "include": [
     "test-configs",
-    "jest.config.js",
+    "vitest.config.ts",
     "**/*.test.ts",
     "**/*.spec.ts",
     "**/*.test.js",

packages/browser/vitest.config.ts

@@ -26,5 +26,6 @@ export default defineConfig({
       instances: [{browser: 'chromium'}],
       provider: 'playwright',
     },
+    globals: true,
   },
 });