feature(next): add suspense option (#157)

* feature(next): Add suspense option

* Update packages/next/src/useNextRouter.ts

Co-authored-by: MinuKang <[email protected]>

---------

Co-authored-by: MinuKang <[email protected]>

Author: Junnis0123

.changeset/hot-candles-drive.md

@@ -0,0 +1,5 @@
+---
+'@use-funnel/next': patch
+---
+
+next: add suspense option

packages/next/src/useFunnel.tsx

@@ -1,6 +1,6 @@
 import { createUseFunnel } from '@use-funnel/core';
-import { useRouter } from 'next/router.js';
 import { useMemo, useRef } from 'react';
+import { useNextRouter } from './useNextRouter';
 import { makePath, parseQueryJson, removeKeys, stringifyQueryJson } from './util';
 
 const QS_KEY = 'funnel.';
@@ -23,6 +23,7 @@ interface NextPageFunnelOption {
   stepQueryName?: (id: string) => string;
   contextQueryName?: (id: string) => string;
   historyQueryName?: (id: string) => string;
+  suspense?: boolean;
 }
 
 export const useFunnel = createUseFunnel<NextPageRouteOption, NextPageFunnelOption>(({
@@ -32,8 +33,9 @@ export const useFunnel = createUseFunnel<NextPageRouteOption, NextPageFunnelOpti
   stepQueryName = (id) => `${QS_KEY}${id}${STEP_KEY}`,
   contextQueryName = (id) => `${QS_KEY}${id}${CONTEXT_KEY}`,
   historyQueryName = (id) => `${QS_KEY}${id}${HISTORY_KEY}`,
+  suspense,
 }) => {
-  const router = useRouter();
+  const router = useNextRouter({ suspense });
 
   const routerRef = useRef(router);
   routerRef.current = router;

packages/next/src/useNextRouter.ts

@@ -0,0 +1,16 @@
+import { useRouter } from 'next/router.js';
+import { waitForRouterReady } from './util';
+
+interface Options {
+  suspense?: boolean;
+}
+
+export function useNextRouter(options: Options = { suspense: false }) {
+  const router = useRouter();
+
+  if (options.suspense && !router.isReady) {
+    throw waitForRouterReady();
+  }
+
+  return router;
+}

packages/next/src/util.ts

@@ -1,4 +1,4 @@
-import { NextRouter } from 'next/router';
+import Router, { NextRouter } from 'next/router';
 
 export const removeKeys = (_value: Record<string, any>, conditions: (string | ((key: string) => boolean))[]) => {
   const value = { ..._value };
@@ -66,3 +66,9 @@ export function stringifyQueryJson(data: unknown) {
     return value;
   });
 }
+
+export function waitForRouterReady() {
+  return new Promise<void>((resolve) => {
+    Router.ready(resolve);
+  });
+}

packages/next/test/index.test.tsx

@@ -1,8 +1,9 @@
-import { render, screen } from '@testing-library/react';
+import { render, screen, waitFor } from '@testing-library/react';
 import { userEvent } from '@testing-library/user-event';
 import mockRouter from 'next-router-mock';
 import { describe, expect, test } from 'vitest';
 import { useFunnel } from '../src/index.js';
+import { renderWithSuspense } from './utils.js';
 
 describe('Test useFunnel next router', () => {
   test('should work', async () => {
@@ -80,6 +81,71 @@ describe('Test useFunnel next router', () => {
     expect(JSON.parse(mockRouter.query['funnel.vitest.histories'] as string)).toEqual([{ step: 'A', context: {} }]);
   });
 
+  describe('should work with suspense option', async () => {
+    function FunnelTest() {
+      const funnel = useFunnel<{
+        A: { id?: string };
+        B: { id: string };
+        C: { id: string; password: string; date: Date };
+      }>({
+        id: 'vitest',
+        initial: {
+          step: 'A',
+          context: {},
+        },
+        suspense: true,
+      });
+
+      switch (funnel.step) {
+        case 'A': {
+          return <div>A</div>;
+        }
+        case 'B': {
+          return <div>B</div>;
+        }
+        case 'C': {
+          return <div>C</div>;
+        }
+        default: {
+          throw new Error('Invalid step');
+        }
+      }
+    }
+
+    test('does not have the query parameter value when `isReady: false`', () => {
+      mockRouter.isReady = false;
+
+      const { checkDidSuspend, withSuspense } = renderWithSuspense();
+      render(withSuspense(<FunnelTest />, { fallback: null }));
+      expect(checkDidSuspend()).toBe(true);
+    });
+
+    test('returns the correct query parameter value when `isReady: true`', async () => {
+      mockRouter.isReady = false;
+
+      const { checkDidSuspend, withSuspense } = renderWithSuspense();
+
+      const FunnelWithSuspense = withSuspense(<FunnelTest />, { fallback: <div>fallback</div> });
+      const page = render(FunnelWithSuspense);
+
+      // set isReady true and rerender page
+      const timer = setTimeout(() => {
+        mockRouter.isReady = true;
+        page.rerender(FunnelWithSuspense);
+        clearTimeout(timer);
+      }, 1000);
+
+      expect(screen.queryByText('fallback')).not.toBeNull();
+
+      await waitFor(() => {
+        expect(screen.queryByText('C')).not.toBeNull();
+        expect(mockRouter.query['funnel.vitest.step']).toBe('C');
+      });
+
+      expect(checkDidSuspend()).toBe(true);
+    });
+  });
+
   // TODO: Fix this test to sync next-router-mock and window.location.search
   test.skip('should work with sub funnel when is multiple used', async () => {
     function SubFunnel(props: { onNext(id: string): void }) {

packages/next/test/utils.tsx

@@ -0,0 +1,21 @@
+import { render } from '@testing-library/react';
+import { ReactNode, Suspense, useEffect } from 'react';
+import { vi } from 'vitest';
+
+export function renderWithSuspense() {
+  const isSuspended = vi.fn(() => null);
+
+  const FallbackComponent = ({ children }: { children: ReactNode }) => {
+    isSuspended();
+    return <>{children}</>;
+  };
+
+  const withSuspense = (children: ReactNode, { fallback }: { fallback: ReactNode }) => {
+    return <Suspense fallback={<FallbackComponent>{fallback}</FallbackComponent>}>{children}</Suspense>;
+  };
+
+  return {
+    withSuspense,
+    checkDidSuspend: () => isSuspended.mock.calls.length > 0,
+  };
+}