feat(web): improve calendar navigation cues (#2173)

* feat(web): improve calendar navigation cues

* refactor(web): simplify calendar interaction states

Author: tyler-dane

packages/web/src/api/util/api.util.ts

@@ -6,7 +6,7 @@ import {
 } from "@core/types/auth.types";
 import { session } from "@web/auth/compass/session/Session";
 import { ENV_WEB } from "@web/common/constants/env.constants";
-import { ROOT_ROUTES } from "@web/common/constants/routes";
+import { DEFAULT_CALENDAR_ROUTE } from "@web/common/constants/routes";
 import {
   assignLocation,
   reloadLocation,
@@ -85,10 +85,10 @@ export const signOut = async (status: SignoutStatus) => {
 
   await session.signOut();
 
-  if (window.location.pathname.startsWith(ROOT_ROUTES.DAY)) {
+  if (window.location.pathname.startsWith(DEFAULT_CALENDAR_ROUTE)) {
     return;
   }
-  assignLocation(ROOT_ROUTES.DAY);
+  assignLocation(DEFAULT_CALENDAR_ROUTE);
 };
 
 export const getRequestUrl = (url: string): string => {

packages/web/src/auth/google/authorization/complete-google-authorization.ts

@@ -4,7 +4,7 @@ import {
   GoogleConnectErrorResponseSchema,
 } from "@core/types/auth.types";
 import { type ApiError, type ApiMethodConfig } from "@web/api/api.types";
-import { ROOT_ROUTES } from "@web/common/constants/routes";
+import { DEFAULT_CALENDAR_ROUTE } from "@web/common/constants/routes";
 import {
   GOOGLE_AUTH_SCOPES_REQUIRED,
   GOOGLE_AUTHORIZATION_ERROR_MESSAGE,
@@ -58,7 +58,7 @@ export type CompleteGoogleAuthorizationResult =
 
 const fail = (
   message = GOOGLE_AUTHORIZATION_ERROR_MESSAGE,
-  returnPath: string = ROOT_ROUTES.DAY,
+  returnPath: string = DEFAULT_CALENDAR_ROUTE,
 ): CompleteGoogleAuthorizationResult => ({
   message,
   returnPath,
@@ -101,7 +101,7 @@ export async function completeGoogleAuthorization({
 
   const savedIntent = readGoogleAuthorizationIntent(state);
   clearGoogleAuthorizationIntent(state);
-  const returnPath = savedIntent?.returnPath ?? ROOT_ROUTES.DAY;
+  const returnPath = savedIntent?.returnPath ?? DEFAULT_CALENDAR_ROUTE;
 
   if (!savedIntent || params.get("error")) {
     return fail(GOOGLE_AUTHORIZATION_ERROR_MESSAGE, returnPath);

packages/web/src/auth/google/authorization/google-authorization.test.ts

@@ -197,7 +197,7 @@ describe("completeGoogleAuthorization", () => {
     ).resolves.toEqual({
       status: "failed",
       message: "We couldn't connect your Google account. Please try again.",
-      returnPath: "/day",
+      returnPath: "/week",
     });
 
     expect(deps.authApi.loginOrSignup).not.toHaveBeenCalled();

packages/web/src/auth/google/authorization/google-authorization.util.test.ts

@@ -30,13 +30,13 @@ describe("google-authorization.util", () => {
     ).toBe("/week/2026-07-08?x=1");
   });
 
-  it("falls back to /day for external return paths", () => {
+  it("falls back to /week for external return paths", () => {
     expect(
       getSafeGoogleAuthReturnPath(
         "https://evil.example/phish",
         "http://localhost:9080",
       ),
-    ).toBe("/day");
+    ).toBe("/week");
   });
 
   it("builds the existing auth-code payload shape", () => {

packages/web/src/auth/google/authorization/google-authorization.util.ts

@@ -1,4 +1,5 @@
 import { type GoogleAuthCodeRequest } from "@core/types/auth.types";
+import { DEFAULT_CALENDAR_ROUTE } from "@web/common/constants/routes";
 import { GOOGLE_AUTH_CALLBACK_PATH } from "./google-authorization.constants";
 
 export function buildGoogleAuthCallbackUrl(origin = window.location.origin) {
@@ -13,11 +14,11 @@ export function getSafeGoogleAuthReturnPath(
     const url = new URL(href, origin);
 
     if (url.origin !== origin) {
-      return "/day";
+      return DEFAULT_CALENDAR_ROUTE;
     }
 
     if (url.pathname === GOOGLE_AUTH_CALLBACK_PATH) {
-      return "/day";
+      return DEFAULT_CALENDAR_ROUTE;
     }
 
     // Drop the transient auth-modal params so the OAuth round-trip doesn't
@@ -28,7 +29,7 @@ export function getSafeGoogleAuthReturnPath(
 
     return `${url.pathname}${url.search}${url.hash}`;
   } catch {
-    return "/day";
+    return DEFAULT_CALENDAR_ROUTE;
   }
 }
 

packages/web/src/auth/google/hooks/useConnectGoogle/useConnectGoogle.ts

@@ -1,43 +1,23 @@
-import { useCallback, useSyncExternalStore } from "react";
+import { useCallback } from "react";
 import { SyncApi } from "@web/api/sync.api";
 import { getApiErrorCode, isApiError } from "@web/api/util/api.util";
-import { hasUserEverAuthenticated } from "@web/auth/compass/state/auth.state.util";
 import { useStartGoogleAuthorization } from "@web/auth/google/authorization/useStartGoogleAuthorization";
 import {
   clearGoogleSyncIndicatorOverride,
-  getGoogleSyncIndicatorOverride,
   setRepairingSyncIndicatorOverride,
-  subscribeToGoogleSyncUIState,
 } from "@web/auth/google/state/google.sync.state";
 import { syncPendingLocalEvents } from "@web/auth/google/util/google.auth.util";
-import {
-  selectGoogleConnectionState,
-  selectUserMetadataStatus,
-  useUserMetadataStore,
-} from "@web/auth/state/user-metadata.store";
 import { GOOGLE_REPAIR_FAILED_TOAST_ID } from "@web/common/constants/toast.constants";
 import { showErrorToast } from "@web/common/utils/toast/error-toast.util";
 import { settingsActions } from "@web/settings/settings.store";
 import { useIsGoogleAvailable } from "../useIsGoogleAvailable/useIsGoogleAvailable";
-import {
-  type GoogleUiState,
-  type UseConnectGoogleResult,
-} from "./useConnectGoogle.types";
+import { type UseConnectGoogleResult } from "./useConnectGoogle.types";
 import { getGoogleConnectionConfig } from "./useConnectGoogle.util";
-
-// Merges store-derived Google connection state with transient UI overrides from
-// google.sync.ui.state.ts; the override is read via useSyncExternalStore so React
-// stays aligned with that external store (see comments there).
+import { useGoogleUiState } from "./useGoogleUiState";
 
 export const useConnectGoogle = (): UseConnectGoogleResult => {
   const isAvailable = useIsGoogleAvailable();
-  const connectionState = useUserMetadataStore(selectGoogleConnectionState);
-  const userMetadataStatus = useUserMetadataStore(selectUserMetadataStatus);
-  const syncIndicator = useSyncExternalStore(
-    subscribeToGoogleSyncUIState,
-    getGoogleSyncIndicatorOverride,
-    getGoogleSyncIndicatorOverride,
-  );
+  const state = useGoogleUiState();
   const { startGoogleAuthorization } = useStartGoogleAuthorization({
     intent: "connectCalendar",
     prompt: "consent",
@@ -88,21 +68,6 @@ export const useConnectGoogle = (): UseConnectGoogleResult => {
     void startRepair();
   }, []);
 
-  // "checking" is a UI-only state until we have loaded metadata from the server.
-  // Covers both "idle" and "loading" so returning users do not briefly see
-  // NOT_CONNECTED from the selector default.
-  const isCheckingStatus =
-    hasUserEverAuthenticated() && userMetadataStatus !== "loaded";
-
-  const state: GoogleUiState =
-    syncIndicator === "repairing"
-      ? "repairing"
-      : syncIndicator === "syncing"
-        ? "IMPORTING"
-        : isCheckingStatus
-          ? "checking"
-          : connectionState;
-
   return {
     ...getGoogleConnectionConfig(state, onOpenGoogleAuth, onRepairGoogle),
     isAvailable,

packages/web/src/auth/google/hooks/useConnectGoogle/useGoogleUiState.test.ts

@@ -0,0 +1,52 @@
+import { act, cleanup, renderHook } from "@testing-library/react";
+import {
+  resetGoogleSyncUIStateForTests,
+  setRepairingSyncIndicatorOverride,
+  setSyncingSyncIndicatorOverride,
+} from "@web/auth/google/state/google.sync.state";
+import { userMetadataActions } from "@web/auth/state/user-metadata.store";
+import { resolveGoogleUiState, useGoogleUiState } from "./useGoogleUiState";
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+
+beforeEach(() => {
+  resetGoogleSyncUIStateForTests();
+  userMetadataActions.clear();
+});
+
+afterEach(() => {
+  cleanup();
+  resetGoogleSyncUIStateForTests();
+  userMetadataActions.clear();
+});
+
+describe("useGoogleUiState", () => {
+  it("reflects the loaded Google connection state", () => {
+    userMetadataActions.set({ google: { connectionState: "HEALTHY" } });
+
+    const { result } = renderHook(() => useGoogleUiState());
+
+    expect(result.current).toBe("HEALTHY");
+  });
+
+  it("prioritizes transient syncing and repair states", () => {
+    userMetadataActions.set({ google: { connectionState: "HEALTHY" } });
+    const { result } = renderHook(() => useGoogleUiState());
+
+    act(() => setSyncingSyncIndicatorOverride());
+    expect(result.current).toBe("IMPORTING");
+
+    act(() => setRepairingSyncIndicatorOverride());
+    expect(result.current).toBe("repairing");
+  });
+
+  it("reports checking while a returning user's metadata loads", () => {
+    expect(
+      resolveGoogleUiState({
+        connectionState: "NOT_CONNECTED",
+        hasAuthenticated: true,
+        syncIndicator: null,
+        userMetadataStatus: "loading",
+      }),
+    ).toBe("checking");
+  });
+});

packages/web/src/auth/google/hooks/useConnectGoogle/useGoogleUiState.ts

@@ -0,0 +1,58 @@
+import { useSyncExternalStore } from "react";
+import { type GoogleConnectionState } from "@core/types/user.types";
+import { hasUserEverAuthenticated } from "@web/auth/compass/state/auth.state.util";
+import {
+  getGoogleSyncIndicatorOverride,
+  subscribeToGoogleSyncUIState,
+} from "@web/auth/google/state/google.sync.state";
+import {
+  selectGoogleConnectionState,
+  selectUserMetadataStatus,
+  type UserMetadataStatus,
+  useUserMetadataStore,
+} from "@web/auth/state/user-metadata.store";
+import { type GoogleUiState } from "./useConnectGoogle.types";
+
+type SyncIndicator = ReturnType<typeof getGoogleSyncIndicatorOverride>;
+
+export function resolveGoogleUiState({
+  connectionState,
+  hasAuthenticated,
+  syncIndicator,
+  userMetadataStatus,
+}: {
+  connectionState: GoogleConnectionState;
+  hasAuthenticated: boolean;
+  syncIndicator: SyncIndicator;
+  userMetadataStatus: UserMetadataStatus;
+}): GoogleUiState {
+  if (syncIndicator === "repairing") return "repairing";
+  if (syncIndicator === "syncing") return "IMPORTING";
+
+  if (hasAuthenticated && userMetadataStatus !== "loaded") {
+    return "checking";
+  }
+
+  return connectionState;
+}
+
+// Merges server metadata with transient repair/import overrides. The external
+// store subscription keeps every sync indicator aligned as SSE updates arrive.
+export function useGoogleUiState(): GoogleUiState {
+  const connectionState = useUserMetadataStore(selectGoogleConnectionState);
+  const userMetadataStatus = useUserMetadataStore(selectUserMetadataStatus);
+  const syncIndicator = useSyncExternalStore(
+    subscribeToGoogleSyncUIState,
+    getGoogleSyncIndicatorOverride,
+    getGoogleSyncIndicatorOverride,
+  );
+
+  // Returning users should not briefly look disconnected while their server
+  // metadata is still loading.
+  return resolveGoogleUiState({
+    connectionState,
+    hasAuthenticated: hasUserEverAuthenticated(),
+    syncIndicator,
+    userMetadataStatus,
+  });
+}

packages/web/src/common/constants/routes.ts

@@ -10,6 +10,8 @@ export const ROOT_ROUTES = {
   DAY_DATE: "/day/$dateString",
 } as const;
 
+export const DEFAULT_CALENDAR_ROUTE = ROOT_ROUTES.WEEK;
+
 // TanStack route *ids* (used for useMatch/useParams `from`), which diverge
 // from the URL-shaped ROOT_ROUTES above under the pathless "authenticated"
 // layout route. Kept as literals rather than importing the route objects

packages/web/src/components/PlannerSidebar/PlannerSidebarActions/PlannerSidebarActions.test.tsx

@@ -1,6 +1,10 @@
-import { render, screen } from "@testing-library/react";
+import { act, render, screen } from "@testing-library/react";
 import { createStoreWrapper } from "@web/__tests__/render-with-store";
-import { afterAll, describe, expect, it, mock } from "bun:test";
+import {
+  resetGoogleSyncUIStateForTests,
+  setSyncingSyncIndicatorOverride,
+} from "@web/auth/google/state/google.sync.state";
+import { afterAll, afterEach, describe, expect, it, mock } from "bun:test";
 
 // mock.module is process-wide and not reliably restorable, so the real hook
 // is captured up front and a flag (flipped off in afterAll) decides which
@@ -28,10 +32,33 @@ afterAll(() => {
   isVersionCheckMocked = false;
 });
 
+afterEach(() => {
+  act(() => resetGoogleSyncUIStateForTests());
+});
+
 const { PlannerSidebarActions } =
   require("@web/components/PlannerSidebar/PlannerSidebarActions/PlannerSidebarActions") as typeof import("@web/components/PlannerSidebar/PlannerSidebarActions/PlannerSidebarActions");
 
 describe("PlannerSidebarActions", () => {
+  it("shimmers the command palette icon while Google Calendar is syncing", () => {
+    const { wrapper } = createStoreWrapper();
+    setSyncingSyncIndicatorOverride();
+
+    render(
+      <PlannerSidebarActions
+        isShortcutsOpen={false}
+        onToggleShortcuts={mock()}
+      />,
+      { wrapper },
+    );
+
+    expect(
+      screen.getByRole("button", {
+        name: "Open command palette, calendar syncing",
+      }),
+    ).toBeInTheDocument();
+  });
+
   it("does not render the background import spinner in the sidebar", () => {
     const { wrapper } = createStoreWrapper();
 
@@ -48,6 +75,9 @@ describe("PlannerSidebarActions", () => {
         name: "Syncing Google Calendar in the background.",
       }),
     ).not.toBeInTheDocument();
+    expect(
+      screen.getByRole("button", { name: "Open command palette" }),
+    ).toBeInTheDocument();
   });
 
   it("labels the shortcuts button as a close action when shortcuts are open", () => {