feat(mosaic): add getSearchParams to the Mosaic router hook

.changeset/mosaic-router-search-params.md

@@ -0,0 +1,2 @@
+---
+---

packages/mosaic/src/hooks/__tests__/use-mosaic-router.feature.test.tsx

@@ -1,9 +1,10 @@
 import { screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import { serveFapi } from '../../__tests__/feature/fake-fapi';
 import { renderWithClerk } from '../../__tests__/feature/render';
+import type { MosaicRouter } from '../use-mosaic-router';
 import { useMosaicRouter } from '../use-mosaic-router';
 
 function Navigation({ to, hard = false }: { to: string; hard?: boolean }) {
@@ -18,6 +19,21 @@ function Navigation({ to, hard = false }: { to: string; hard?: boolean }) {
   );
 }
 
+function CaptureRouter({ onRouter }: { onRouter: (router: MosaicRouter) => void }) {
+  onRouter(useMosaicRouter());
+  return null;
+}
+
+async function renderRouter() {
+  serveFapi();
+  let captured: MosaicRouter | undefined;
+  await renderWithClerk(<CaptureRouter onRouter={router => (captured = router)} />);
+  if (!captured) {
+    throw new Error('Router was not rendered');
+  }
+  return captured;
+}
+
 describe('Mosaic router', () => {
   it('uses the host router for ordinary same-origin navigation', async () => {
     serveFapi();
@@ -87,4 +103,41 @@ describe('Mosaic router', () => {
       }
     }
   });
+
+  describe('getSearchParams', () => {
+    const originalUrl = window.location.href;
+
+    afterEach(() => {
+      window.history.replaceState(null, '', originalUrl);
+    });
+
+    it('reads the current query with values decoded', async () => {
+      const router = await renderRouter();
+      window.history.replaceState(null, '', '?email_address=bob%40example.com');
+      expect(router.getSearchParams().get('email_address')).toBe('bob@example.com');
+    });
+
+    it('returns null for a key that is not in the query', async () => {
+      const router = await renderRouter();
+      window.history.replaceState(null, '', '?email_address=bob%40example.com');
+      expect(router.getSearchParams().get('missing')).toBeNull();
+    });
+
+    it('reads the latest query after the URL changes', async () => {
+      const router = await renderRouter();
+      window.history.replaceState(null, '', '?step=one');
+      expect(router.getSearchParams().get('step')).toBe('one');
+      window.history.replaceState(null, '', '?step=two');
+      expect(router.getSearchParams().get('step')).toBe('two');
+    });
+
+    it('returns a fresh instance on each call', async () => {
+      const router = await renderRouter();
+      window.history.replaceState(null, '', '?step=one');
+      const first = router.getSearchParams();
+      first.set('step', 'two');
+      first.append('extra', 'value');
+      expect(router.getSearchParams().toString()).toBe('step=one');
+    });
+  });
 });

packages/mosaic/src/hooks/__tests__/use-mosaic-router.ssr.test.tsx

@@ -0,0 +1,43 @@
+// @vitest-environment node
+import { Clerk } from '@clerk/clerk-js';
+import { ClerkContextProvider } from '@clerk/shared/react';
+import { renderToString } from 'react-dom/server';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { MosaicRouter } from '../use-mosaic-router';
+import { useMosaicRouter } from '../use-mosaic-router';
+
+function CaptureRouter({ onRouter }: { onRouter: (router: MosaicRouter) => void }) {
+  onRouter(useMosaicRouter());
+  return null;
+}
+
+function renderRouterOnServer() {
+  const clerk = new Clerk(`pk_test_${btoa('clerk.example.com$')}`);
+  let captured: MosaicRouter | undefined;
+  renderToString(
+    <ClerkContextProvider
+      clerk={clerk}
+      clerkStatus={clerk.status}
+    >
+      <CaptureRouter onRouter={router => (captured = router)} />
+    </ClerkContextProvider>,
+  );
+  if (!captured) {
+    throw new Error('Router was not rendered');
+  }
+  return captured;
+}
+
+describe('Mosaic router on the server', () => {
+  it('returns empty search params when there is no window', () => {
+    const router = renderRouterOnServer();
+    expect(router.getSearchParams().toString()).toBe('');
+  });
+
+  it('returns empty search params when the window has no location', () => {
+    const router = renderRouterOnServer();
+    vi.stubGlobal('window', {});
+    expect(router.getSearchParams().toString()).toBe('');
+  });
+});

packages/mosaic/src/hooks/use-mosaic-router.ts

@@ -4,6 +4,7 @@ import { useClerk } from '@clerk/shared/react';
 export interface MosaicRouter {
   navigate: (to: string) => void | Promise<unknown>;
   windowNavigate: (to: URL | string) => void;
+  getSearchParams: () => URLSearchParams;
 }
 
 /**
@@ -25,5 +26,6 @@ export function useMosaicRouter(): MosaicRouter {
         windowNavigate(to);
       }
     },
+    getSearchParams: () => new URLSearchParams(typeof window !== 'undefined' ? (window.location?.search ?? '') : ''),
   };
 }