#69 add onboarding flow

Author: jayhill

frontend/src/components/app/App.tsx

@@ -16,6 +16,11 @@ import Clients from '../../pages/Clients';
 import Settings from '../../pages/Settings';
 import Help from '../../pages/Help';
 
+import React, { useContext, useEffect } from 'react';
+import { AppContext } from './AppContext';
+import { useZipCaseApi } from '../../hooks';
+import { useNavigate, useLocation } from 'react-router-dom';
+
 // Create theme for Amplify UI components
 const amplifyTheme = {
     tokens: {
@@ -130,30 +135,72 @@ const components = {
     },
 };
 
+// Onboarding logic: check for portal credentials on login, set firstTimeUser, and redirect if needed
 const App: React.FC = () => {
     return (
         <ThemeProvider theme={{ ...defaultTheme, ...amplifyTheme }}>
             <Authenticator hideSignUp={true} components={components}>
                 <QueryClientProvider client={queryClient}>
-                    <AppContextProvider>
-                        <BrowserRouter>
-                            <Routes>
-                                <Route path="/" element={<Navigate to="/search/case" />} />
-                                <Route element={<Shell />}>
-                                    <Route path="/search" element={<Navigate to="/search/case" />} />
-                                    <Route path="/search/case" element={<Search type="case" />} />
-                                    <Route path="/search/name" element={<Search type="name" />} />
-                                    <Route path="/clients" element={<Clients />} />
-                                    <Route path="/settings" element={<Settings />} />
-                                    <Route path="/help" element={<Help />} />
-                                </Route>
-                            </Routes>
-                        </BrowserRouter>
-                    </AppContextProvider>
+                    <BrowserRouter>
+                        <AppContextProvider>
+                            <OnboardingRouter />
+                        </AppContextProvider>
+                    </BrowserRouter>
                 </QueryClientProvider>
             </Authenticator>
         </ThemeProvider>
     );
 };
 
+const OnboardingRouter: React.FC = () => {
+    const { dispatch } = useContext(AppContext);
+    const getPortalCredentials = useZipCaseApi(client => client.credentials.get()).callApi;
+    const [checked, setChecked] = React.useState(false);
+    const navigate = useNavigate();
+    const location = useLocation();
+
+    useEffect(() => {
+        // Check onboarding on first mount and on login (when location or credentials change)
+        let cancelled = false;
+        (async () => {
+            try {
+                const resp = await getPortalCredentials();
+                const isFirstTime = !resp.success || !resp.data || !resp.data.username;
+                dispatch({ type: 'SET_FIRST_TIME_USER', payload: isFirstTime });
+                if (isFirstTime && location.pathname.startsWith('/search')) {
+                    navigate('/settings', { replace: true });
+                }
+            } catch {
+                dispatch({ type: 'SET_FIRST_TIME_USER', payload: true });
+                if (location.pathname.startsWith('/search')) {
+                    navigate('/settings', { replace: true });
+                }
+            } finally {
+                if (!cancelled) setChecked(true);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+        // Run on mount and when location changes (to catch initial login)
+    }, [location.pathname, dispatch, getPortalCredentials, navigate]);
+
+    // Wait until onboarding check is done before rendering routes
+    if (!checked) return null;
+
+    return (
+        <Routes>
+            <Route path="/" element={<Navigate to="/search/case" />} />
+            <Route element={<Shell />}>
+                <Route path="/search" element={<Navigate to="/search/case" />} />
+                <Route path="/search/case" element={<Search type="case" />} />
+                <Route path="/search/name" element={<Search type="name" />} />
+                <Route path="/clients" element={<Clients />} />
+                <Route path="/settings" element={<Settings />} />
+                <Route path="/help" element={<Help />} />
+            </Route>
+        </Routes>
+    );
+};
+
 export default App;

frontend/src/components/app/AppContext.tsx

@@ -2,23 +2,29 @@ import { createContext, Dispatch } from 'react';
 
 export interface AppContextType {
     token: string;
+    firstTimeUser: boolean;
     dispatch: Dispatch<AppContextAction>;
 }
 
 export const defaultContext = {
     token: '',
+    firstTimeUser: false,
     dispatch: () => {},
 };
 
 export const AppContext = createContext<AppContextType>(defaultContext);
 
-export type AppContextAction = { type: 'SET_TOKEN'; payload: string };
+export type AppContextAction =
+    | { type: 'SET_TOKEN'; payload: string }
+    | { type: 'SET_FIRST_TIME_USER'; payload: boolean };
 
 export const appReducer = (state: AppContextType, action: AppContextAction): AppContextType => {
     switch (action.type) {
         case 'SET_TOKEN':
             return { ...state, token: action.payload };
+        case 'SET_FIRST_TIME_USER':
+            return { ...state, firstTimeUser: action.payload };
         default:
             return state;
     }
-};
+};

frontend/src/pages/Settings.tsx

@@ -1,6 +1,13 @@
-import React from 'react';
+import React, { useContext, useState } from 'react';
 import { useQuery } from '@tanstack/react-query';
-import { SettingsPortalCredentials, SettingsApiKeys } from '../components';
+import { SettingsPortalCredentials, SettingsApiKeys, TextLink } from '../components';
+import {
+    Dialog,
+    DialogTitle,
+    DialogDescription,
+    DialogBody,
+    DialogActions,
+} from '../components/tailwind/dialog';
 import { useZipCaseApi } from '../hooks';
 import { AppContext } from '../components/app/AppContext';
 
@@ -29,10 +36,56 @@ const Settings: React.FC = () => {
                 }),
     });
 
+    // Onboarding modal logic
+    const { firstTimeUser, dispatch } = useContext(AppContext);
+    const [showModal, setShowModal] = useState(firstTimeUser);
+    const [hasVisited, setHasVisited] = useState(false);
+
+    React.useEffect(() => {
+        if (firstTimeUser && !hasVisited) {
+            setShowModal(true);
+            setHasVisited(true);
+        }
+    }, [firstTimeUser, hasVisited]);
+
+    const handleClose = () => {
+        setShowModal(false);
+        dispatch({ type: 'SET_FIRST_TIME_USER', payload: false });
+    };
+
     return (
         <>
             <SettingsPortalCredentials portalCredentials={credentialsQuery} />
             <SettingsApiKeys apiSettings={apiSettingsQuery} />
+            <Dialog open={showModal} onClose={handleClose} size="md">
+                <DialogTitle>Welcome to ZipCase!</DialogTitle>
+                <DialogDescription>
+                    <span role="img" aria-label="wave">
+                        👋
+                    </span>{' '}
+                    Before you can start looking up cases, you'll need to add your court portal
+                    credentials here.
+                </DialogDescription>
+                <DialogBody>
+                    <p className="mb-2">
+                        If you have questions about why we need your credentials or how your data is
+                        protected, check out our{' '}
+                        <TextLink href="/help" onClick={handleClose}>
+                            FAQ
+                        </TextLink>
+                        .
+                    </p>
+                </DialogBody>
+                <DialogActions>
+                    <button
+                        type="button"
+                        onClick={handleClose}
+                        className="bg-primary hover:bg-primary-light active:bg-primary-dark rounded-md px-3 py-2 text-sm font-semibold text-white shadow-xs focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary"
+                    >
+                        Got it
+                    </button>
+                </DialogActions>
+            </Dialog>
         </>
     );
 };