@lobehub/lobehub 2.0.0-next.236 → 2.0.0-next.238

package/src/store/user/slices/onboarding/action.test.ts

@@ -0,0 +1,342 @@
+import { CURRENT_ONBOARDING_VERSION } from '@lobechat/const';
+import { MAX_ONBOARDING_STEPS } from '@lobechat/types';
+import { act, renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { userService } from '@/services/user';
+import { useUserStore } from '@/store/user';
+
+import { initialOnboardingState } from './initialState';
+
+vi.mock('zustand/traditional');
+
+vi.mock('@/services/user', () => ({
+  userService: {
+    updateOnboarding: vi.fn(),
+  },
+}));
+
+describe('onboarding actions', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    act(() => {
+      useUserStore.setState({
+        ...initialOnboardingState,
+        onboarding: { currentStep: 1, version: CURRENT_ONBOARDING_VERSION },
+        refreshUserState: vi.fn(),
+      });
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('goToNextStep', () => {
+    it('should increment step and set localOnboardingStep', () => {
+      const { result } = renderHook(() => useUserStore());
+
+      act(() => {
+        useUserStore.setState({
+          ...initialOnboardingState,
+          onboarding: { currentStep: 1, version: CURRENT_ONBOARDING_VERSION },
+        });
+      });
+
+      act(() => {
+        result.current.goToNextStep();
+      });
+
+      expect(result.current.localOnboardingStep).toBe(2);
+    });
+
+    it('should not increment step when already at MAX_ONBOARDING_STEPS', () => {
+      const { result } = renderHook(() => useUserStore());
+
+      act(() => {
+        useUserStore.setState({
+          ...initialOnboardingState,
+          localOnboardingStep: MAX_ONBOARDING_STEPS,
+          onboarding: { currentStep: MAX_ONBOARDING_STEPS, version: CURRENT_ONBOARDING_VERSION },
+        });
+      });
+
+      act(() => {
+        result.current.goToNextStep();
+      });
+
+      // localOnboardingStep should remain at MAX_ONBOARDING_STEPS
+      expect(result.current.localOnboardingStep).toBe(MAX_ONBOARDING_STEPS);
+    });
+
+    it('should queue step update when incrementing', () => {
+      const { result } = renderHook(() => useUserStore());
+
+      const queueStepUpdateSpy = vi.spyOn(result.current, 'internal_queueStepUpdate');
+
+      act(() => {
+        useUserStore.setState({
+          ...initialOnboardingState,
+          onboarding: { currentStep: 2, version: CURRENT_ONBOARDING_VERSION },
+        });
+      });
+
+      act(() => {
+        result.current.goToNextStep();
+      });
+
+      expect(queueStepUpdateSpy).toHaveBeenCalledWith(3);
+    });
+
+    it('should not queue step update when at MAX_ONBOARDING_STEPS', () => {
+      const { result } = renderHook(() => useUserStore());
+
+      const queueStepUpdateSpy = vi.spyOn(result.current, 'internal_queueStepUpdate');
+
+      act(() => {
+        useUserStore.setState({
+          ...initialOnboardingState,
+          localOnboardingStep: MAX_ONBOARDING_STEPS,
+          onboarding: { currentStep: MAX_ONBOARDING_STEPS, version: CURRENT_ONBOARDING_VERSION },
+        });
+      });
+
+      act(() => {
+        result.current.goToNextStep();
+      });
+
+      expect(queueStepUpdateSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('goToPreviousStep', () => {
+    it('should decrement step and set localOnboardingStep', () => {
+      const { result } = renderHook(() => useUserStore());
+
+      act(() => {
+        useUserStore.setState({
+          ...initialOnboardingState,
+          localOnboardingStep: 3,
+          onboarding: { currentStep: 3, version: CURRENT_ONBOARDING_VERSION },
+        });
+      });
+
+      act(() => {
+        result.current.goToPreviousStep();
+      });
+
+      expect(result.current.localOnboardingStep).toBe(2);
+    });
+
+    it('should not decrement step when already at step 1', () => {
+      const { result } = renderHook(() => useUserStore());
+
+      act(() => {
+        useUserStore.setState({
+          ...initialOnboardingState,
+          localOnboardingStep: 1,
+          onboarding: { currentStep: 1, version: CURRENT_ONBOARDING_VERSION },
+        });
+      });
+
+      act(() => {
+        result.current.goToPreviousStep();
+      });
+
+      // localOnboardingStep should remain at 1
+      expect(result.current.localOnboardingStep).toBe(1);
+    });
+
+    it('should queue step update when decrementing', () => {
+      const { result } = renderHook(() => useUserStore());
+
+      const queueStepUpdateSpy = vi.spyOn(result.current, 'internal_queueStepUpdate');
+
+      act(() => {
+        useUserStore.setState({
+          ...initialOnboardingState,
+          localOnboardingStep: 3,
+          onboarding: { currentStep: 3, version: CURRENT_ONBOARDING_VERSION },
+        });
+      });
+
+      act(() => {
+        result.current.goToPreviousStep();
+      });
+
+      expect(queueStepUpdateSpy).toHaveBeenCalledWith(2);
+    });
+
+    it('should not queue step update when at step 1', () => {
+      const { result } = renderHook(() => useUserStore());
+
+      const queueStepUpdateSpy = vi.spyOn(result.current, 'internal_queueStepUpdate');
+
+      act(() => {
+        useUserStore.setState({
+          ...initialOnboardingState,
+          localOnboardingStep: 1,
+          onboarding: { currentStep: 1, version: CURRENT_ONBOARDING_VERSION },
+        });
+      });
+
+      act(() => {
+        result.current.goToPreviousStep();
+      });
+
+      expect(queueStepUpdateSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('internal_queueStepUpdate', () => {
+    it('should add task to empty queue and start processing', () => {
+      const { result } = renderHook(() => useUserStore());
+
+      act(() => {
+        useUserStore.setState({
+          ...initialOnboardingState,
+          stepUpdateQueue: [],
+        });
+      });
+
+      const processSpy = vi.spyOn(result.current, 'internal_processStepUpdateQueue');
+
+      act(() => {
+        result.current.internal_queueStepUpdate(2);
+      });
+
+      expect(result.current.stepUpdateQueue).toContain(2);
+      expect(processSpy).toHaveBeenCalled();
+    });
+
+    it('should add pending task when one task is executing', () => {
+      const { result } = renderHook(() => useUserStore());
+
+      act(() => {
+        useUserStore.setState({
+          ...initialOnboardingState,
+          stepUpdateQueue: [2],
+          isProcessingStepQueue: true,
+        });
+      });
+
+      act(() => {
+        result.current.internal_queueStepUpdate(3);
+      });
+
+      expect(result.current.stepUpdateQueue).toEqual([2, 3]);
+    });
+
+    it('should replace pending task when queue has two tasks', () => {
+      const { result } = renderHook(() => useUserStore());
+
+      act(() => {
+        useUserStore.setState({
+          ...initialOnboardingState,
+          stepUpdateQueue: [2, 3],
+          isProcessingStepQueue: true,
+        });
+      });
+
+      act(() => {
+        result.current.internal_queueStepUpdate(4);
+      });
+
+      expect(result.current.stepUpdateQueue).toEqual([2, 4]);
+    });
+  });
+
+  describe('internal_processStepUpdateQueue', () => {
+    it('should not process when already processing', async () => {
+      const { result } = renderHook(() => useUserStore());
+
+      act(() => {
+        useUserStore.setState({
+          ...initialOnboardingState,
+          stepUpdateQueue: [2],
+          isProcessingStepQueue: true,
+        });
+      });
+
+      await act(async () => {
+        await result.current.internal_processStepUpdateQueue();
+      });
+
+      // userService.updateOnboarding should not be called
+      expect(userService.updateOnboarding).not.toHaveBeenCalled();
+    });
+
+    it('should not process when queue is empty', async () => {
+      const { result } = renderHook(() => useUserStore());
+
+      act(() => {
+        useUserStore.setState({
+          ...initialOnboardingState,
+          stepUpdateQueue: [],
+          isProcessingStepQueue: false,
+        });
+      });
+
+      await act(async () => {
+        await result.current.internal_processStepUpdateQueue();
+      });
+
+      expect(userService.updateOnboarding).not.toHaveBeenCalled();
+    });
+
+    it('should process queue and call userService.updateOnboarding', async () => {
+      const { result } = renderHook(() => useUserStore());
+
+      vi.mocked(userService.updateOnboarding).mockResolvedValue({} as any);
+
+      act(() => {
+        useUserStore.setState({
+          ...initialOnboardingState,
+          stepUpdateQueue: [2],
+          isProcessingStepQueue: false,
+          onboarding: { version: CURRENT_ONBOARDING_VERSION },
+          refreshUserState: vi.fn(),
+        });
+      });
+
+      await act(async () => {
+        await result.current.internal_processStepUpdateQueue();
+      });
+
+      expect(userService.updateOnboarding).toHaveBeenCalledWith({
+        currentStep: 2,
+        finishedAt: undefined,
+        version: CURRENT_ONBOARDING_VERSION,
+      });
+    });
+
+    it('should handle errors gracefully and continue processing', async () => {
+      const { result } = renderHook(() => useUserStore());
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      vi.mocked(userService.updateOnboarding).mockRejectedValueOnce(new Error('Update failed'));
+
+      act(() => {
+        useUserStore.setState({
+          ...initialOnboardingState,
+          stepUpdateQueue: [2],
+          isProcessingStepQueue: false,
+          onboarding: { version: CURRENT_ONBOARDING_VERSION },
+          refreshUserState: vi.fn(),
+        });
+      });
+
+      await act(async () => {
+        await result.current.internal_processStepUpdateQueue();
+      });
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        'Failed to update onboarding step:',
+        expect.any(Error),
+      );
+      expect(result.current.isProcessingStepQueue).toBe(false);
+
+      consoleErrorSpy.mockRestore();
+    });
+  });
+});

package/src/store/user/slices/onboarding/action.ts

@@ -1,4 +1,5 @@
 import { CURRENT_ONBOARDING_VERSION, INBOX_SESSION_ID } from '@lobechat/const';
+import { MAX_ONBOARDING_STEPS } from '@lobechat/types';
 import type { StateCreator } from 'zustand/vanilla';
 
 import { userService } from '@/services/user';
@@ -51,25 +52,19 @@ export const createOnboardingSlice: StateCreator<
 
   goToNextStep: () => {
     const currentStep = onboardingSelectors.currentStep(get());
-    const nextStep = currentStep + 1;
+    if (currentStep === MAX_ONBOARDING_STEPS) return;
 
-    // Optimistic update: immediately update local state
+    const nextStep = currentStep + 1;
     set({ localOnboardingStep: nextStep }, false, 'goToNextStep/optimistic');
-
-    // Queue the server update
     get().internal_queueStepUpdate(nextStep);
   },
 
   goToPreviousStep: () => {
     const currentStep = onboardingSelectors.currentStep(get());
-    if (currentStep <= 1) return;
+    if (currentStep === 1) return;
 
     const prevStep = currentStep - 1;
-
-    // Optimistic update: immediately update local state
     set({ localOnboardingStep: prevStep }, false, 'goToPreviousStep/optimistic');
-
-    // Queue the server update
     get().internal_queueStepUpdate(prevStep);
   },
 

package/src/store/user/slices/onboarding/selectors.test.ts

@@ -0,0 +1,222 @@
+import { CURRENT_ONBOARDING_VERSION } from '@lobechat/const';
+import { MAX_ONBOARDING_STEPS } from '@lobechat/types';
+import { describe, expect, it } from 'vitest';
+
+import type { UserStore } from '@/store/user';
+
+import { initialOnboardingState } from './initialState';
+import { onboardingSelectors } from './selectors';
+
+describe('onboardingSelectors', () => {
+  describe('currentStep', () => {
+    it('should return localOnboardingStep when set', () => {
+      const store = {
+        ...initialOnboardingState,
+        localOnboardingStep: 3,
+        onboarding: { currentStep: 1, version: CURRENT_ONBOARDING_VERSION },
+      } as unknown as UserStore;
+
+      expect(onboardingSelectors.currentStep(store)).toBe(3);
+    });
+
+    it('should return onboarding.currentStep when localOnboardingStep is undefined', () => {
+      const store = {
+        ...initialOnboardingState,
+        localOnboardingStep: undefined,
+        onboarding: { currentStep: 4, version: CURRENT_ONBOARDING_VERSION },
+      } as unknown as UserStore;
+
+      expect(onboardingSelectors.currentStep(store)).toBe(4);
+    });
+
+    it('should return 1 when both localOnboardingStep and onboarding.currentStep are undefined', () => {
+      const store = {
+        ...initialOnboardingState,
+        localOnboardingStep: undefined,
+        onboarding: undefined,
+      } as unknown as UserStore;
+
+      expect(onboardingSelectors.currentStep(store)).toBe(1);
+    });
+
+    it('should clamp step to minimum of 1 when step is less than 1', () => {
+      const store = {
+        ...initialOnboardingState,
+        localOnboardingStep: 0,
+        onboarding: undefined,
+      } as unknown as UserStore;
+
+      expect(onboardingSelectors.currentStep(store)).toBe(1);
+    });
+
+    it('should clamp step to minimum of 1 when step is negative', () => {
+      const store = {
+        ...initialOnboardingState,
+        localOnboardingStep: -5,
+        onboarding: undefined,
+      } as unknown as UserStore;
+
+      expect(onboardingSelectors.currentStep(store)).toBe(1);
+    });
+
+    it('should clamp step to MAX_ONBOARDING_STEPS when step exceeds maximum', () => {
+      const store = {
+        ...initialOnboardingState,
+        localOnboardingStep: 10,
+        onboarding: undefined,
+      } as unknown as UserStore;
+
+      expect(onboardingSelectors.currentStep(store)).toBe(MAX_ONBOARDING_STEPS);
+    });
+
+    it('should clamp server state step to MAX_ONBOARDING_STEPS when it exceeds maximum', () => {
+      const store = {
+        ...initialOnboardingState,
+        localOnboardingStep: undefined,
+        onboarding: { currentStep: 29, version: CURRENT_ONBOARDING_VERSION },
+      } as unknown as UserStore;
+
+      expect(onboardingSelectors.currentStep(store)).toBe(MAX_ONBOARDING_STEPS);
+    });
+
+    it('should return exact step when within valid range', () => {
+      for (let step = 1; step <= MAX_ONBOARDING_STEPS; step++) {
+        const store = {
+          ...initialOnboardingState,
+          localOnboardingStep: step,
+          onboarding: undefined,
+        } as unknown as UserStore;
+
+        expect(onboardingSelectors.currentStep(store)).toBe(step);
+      }
+    });
+  });
+
+  describe('version', () => {
+    it('should return onboarding version', () => {
+      const store = {
+        ...initialOnboardingState,
+        onboarding: { version: 2 },
+      } as unknown as UserStore;
+
+      expect(onboardingSelectors.version(store)).toBe(2);
+    });
+
+    it('should return CURRENT_ONBOARDING_VERSION when onboarding is undefined', () => {
+      const store = {
+        ...initialOnboardingState,
+        onboarding: undefined,
+      } as unknown as UserStore;
+
+      expect(onboardingSelectors.version(store)).toBe(CURRENT_ONBOARDING_VERSION);
+    });
+  });
+
+  describe('finishedAt', () => {
+    it('should return finishedAt when set', () => {
+      const finishedAt = '2024-01-01T00:00:00Z';
+      const store = {
+        ...initialOnboardingState,
+        onboarding: { finishedAt, version: CURRENT_ONBOARDING_VERSION },
+      } as unknown as UserStore;
+
+      expect(onboardingSelectors.finishedAt(store)).toBe(finishedAt);
+    });
+
+    it('should return undefined when onboarding is undefined', () => {
+      const store = {
+        ...initialOnboardingState,
+        onboarding: undefined,
+      } as unknown as UserStore;
+
+      expect(onboardingSelectors.finishedAt(store)).toBeUndefined();
+    });
+  });
+
+  describe('isFinished', () => {
+    it('should return true when finishedAt is set', () => {
+      const store = {
+        ...initialOnboardingState,
+        onboarding: { finishedAt: '2024-01-01T00:00:00Z', version: CURRENT_ONBOARDING_VERSION },
+      } as unknown as UserStore;
+
+      expect(onboardingSelectors.isFinished(store)).toBe(true);
+    });
+
+    it('should return false when finishedAt is undefined', () => {
+      const store = {
+        ...initialOnboardingState,
+        onboarding: { version: CURRENT_ONBOARDING_VERSION },
+      } as unknown as UserStore;
+
+      expect(onboardingSelectors.isFinished(store)).toBe(false);
+    });
+
+    it('should return false when onboarding is undefined', () => {
+      const store = {
+        ...initialOnboardingState,
+        onboarding: undefined,
+      } as unknown as UserStore;
+
+      expect(onboardingSelectors.isFinished(store)).toBe(false);
+    });
+  });
+
+  describe('needsOnboarding', () => {
+    it('should return true when finishedAt is not set', () => {
+      const store = {
+        onboarding: { version: CURRENT_ONBOARDING_VERSION },
+      } as Pick<UserStore, 'onboarding'>;
+
+      expect(onboardingSelectors.needsOnboarding(store)).toBe(true);
+    });
+
+    it('should return true when version is older than current', () => {
+      // If CURRENT_ONBOARDING_VERSION > 1, test with version 1
+      // Otherwise, this test is not applicable since there's no valid older version
+      if (CURRENT_ONBOARDING_VERSION > 1) {
+        const store = {
+          onboarding: {
+            finishedAt: '2024-01-01T00:00:00Z',
+            version: 1,
+          },
+        } as Pick<UserStore, 'onboarding'>;
+
+        expect(onboardingSelectors.needsOnboarding(store)).toBe(true);
+      } else {
+        // When CURRENT_ONBOARDING_VERSION is 1, there's no valid older version (0 is falsy)
+        // Test that version 0 is treated as NOT needing onboarding due to falsy check
+        const store = {
+          onboarding: {
+            finishedAt: '2024-01-01T00:00:00Z',
+            version: 0,
+          },
+        } as Pick<UserStore, 'onboarding'>;
+
+        // version 0 is falsy, so the condition (version && version < CURRENT) short-circuits to 0 (falsy)
+        // finishedAt is set, so the first condition is false
+        // The result is falsy (0), not strictly false
+        expect(onboardingSelectors.needsOnboarding(store)).toBeFalsy();
+      }
+    });
+
+    it('should return false when finishedAt is set and version is current', () => {
+      const store = {
+        onboarding: {
+          finishedAt: '2024-01-01T00:00:00Z',
+          version: CURRENT_ONBOARDING_VERSION,
+        },
+      } as Pick<UserStore, 'onboarding'>;
+
+      expect(onboardingSelectors.needsOnboarding(store)).toBe(false);
+    });
+
+    it('should return true when onboarding is undefined', () => {
+      const store = {
+        onboarding: undefined,
+      } as Pick<UserStore, 'onboarding'>;
+
+      expect(onboardingSelectors.needsOnboarding(store)).toBe(true);
+    });
+  });
+});

package/src/store/user/slices/onboarding/selectors.ts

@@ -1,12 +1,17 @@
 import { CURRENT_ONBOARDING_VERSION } from '@lobechat/const';
+import { MAX_ONBOARDING_STEPS } from '@lobechat/types';
 
 import type { UserStore } from '../../store';
 
 /**
  * Returns the current step for UI display.
  * Prioritizes local optimistic state over server state for immediate feedback.
+ * Clamps the value to valid range [1, MAX_ONBOARDING_STEPS].
  */
-const currentStep = (s: UserStore) => s.localOnboardingStep ?? s.onboarding?.currentStep ?? 1;
+const currentStep = (s: UserStore) => {
+  const step = s.localOnboardingStep ?? s.onboarding?.currentStep ?? 1;
+  return Math.max(1, Math.min(step, MAX_ONBOARDING_STEPS));
+};
 
 const version = (s: UserStore) => s.onboarding?.version ?? CURRENT_ONBOARDING_VERSION;