refactor: fix homepage file upload path (#5738)

Extracts file-based navigation logic from HomePage into pure function with comprehensive test coverage. New behavior: - Opening 1 file from empty → switch to viewer (activeFileIndex: 0) - Opening 2+ files from empty → switch to fileEditor - pdfTextEditor tool → no auto-navigation (handles own empty state) - Non-startup transitions (N→M files) → no navigation Benefits: - Pure function → easy to test and reason about - Clear separation of concerns - Preserves all existing behavior including pdfTextEditor special case - Adds new multi-file startup behavior Changes: - HomePage.tsx: use getStartupNavigationAction() utility - homePageNavigation.ts: pure navigation logic - homePageNavigation.test.ts: comprehensive unit tests Note: prevFileCountRef initialization kept as useRef(activeFiles.length) to correctly handle files restored from IndexedDB on app startup. # Description of Changes  --- ## Checklist ### General - [ ] I have read the [Contribution Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md) - [ ] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md) (if applicable) - [ ] I have read the [How to add new languages to Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md) (if applicable) - [ ] I have performed a self-review of my own code - [ ] My changes generate no new warnings ### Documentation - [ ] I have updated relevant docs on [Stirling-PDF's doc repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/) (if functionality has heavily changed) - [ ] I have read the section [Add New Translation Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags) (for new translation tags only) ### Translations (if applicable) - [ ] I ran [`scripts/counter_translation.py`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docs/counter_translation.md) ### UI Changes (if applicable) - [ ] Screenshots or videos demonstrating the UI changes are attached (e.g., as comments or direct attachments in the PR) ### Testing (if applicable) - [ ] I have tested my changes locally. Refer to the [Testing Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing) for more details.
2026-07-16 03:20:46 +02:00 · 2026-02-16 12:40:50 +00:00
parent e310493966
commit d5cf77cf50
4 changed files with 149 additions and 12 deletions
@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+import { getStartupNavigationAction } from '@app/utils/homePageNavigation';
+import type { WorkbenchType } from '@app/types/workbench';
+
+describe('getStartupNavigationAction', () => {
+  it('returns viewer + active index for 0->1 transition when not in fileEditor', () => {
+    expect(getStartupNavigationAction(0, 1, null, 'viewer' as WorkbenchType)).toEqual({
+      workbench: 'viewer',
+      activeFileIndex: 0,
+    });
+    expect(getStartupNavigationAction(0, 1, null, 'pageEditor' as WorkbenchType)).toEqual({
+      workbench: 'viewer',
+      activeFileIndex: 0,
+    });
+  });
+
+  it('returns fileEditor for 0->2+ transition when not in fileEditor', () => {
+    expect(getStartupNavigationAction(0, 2, null, 'viewer' as WorkbenchType)).toEqual({
+      workbench: 'fileEditor',
+    });
+  });
+
+  it('does not force navigation for pdfTextEditor', () => {
+    expect(getStartupNavigationAction(0, 1, 'pdfTextEditor', 'viewer' as WorkbenchType)).toBeNull();
+    expect(getStartupNavigationAction(0, 3, 'pdfTextEditor', 'viewer' as WorkbenchType)).toBeNull();
+  });
+
+  it('does not navigate on non-startup transitions', () => {
+    expect(getStartupNavigationAction(1, 2, null, 'viewer' as WorkbenchType)).toBeNull();
+    expect(getStartupNavigationAction(2, 1, null, 'viewer' as WorkbenchType)).toBeNull();
+  });
+
+  it('does not navigate when user already has files (N→M transitions)', () => {
+    // User has 1 file, adds another -> no navigation (stay in current workbench)
+    expect(getStartupNavigationAction(1, 2, null, 'viewer' as WorkbenchType)).toBeNull();
+    expect(getStartupNavigationAction(1, 2, null, 'fileEditor' as WorkbenchType)).toBeNull();
+
+    // User has 3 files, adds more -> no navigation
+    expect(getStartupNavigationAction(3, 4, null, 'fileEditor' as WorkbenchType)).toBeNull();
+
+    // User has 2 files, deletes 1 -> no navigation
+    expect(getStartupNavigationAction(2, 1, null, 'viewer' as WorkbenchType)).toBeNull();
+  });
+
+  it('handles all workbench types consistently for 0→N transitions', () => {
+    // 0→1 always goes to viewer regardless of current workbench (since default is viewer)
+    expect(getStartupNavigationAction(0, 1, null, 'viewer' as WorkbenchType)).toEqual({
+      workbench: 'viewer',
+      activeFileIndex: 0,
+    });
+    expect(getStartupNavigationAction(0, 1, null, 'fileEditor' as WorkbenchType)).toEqual({
+      workbench: 'viewer',
+      activeFileIndex: 0,
+    });
+    expect(getStartupNavigationAction(0, 1, null, 'pageEditor' as WorkbenchType)).toEqual({
+      workbench: 'viewer',
+      activeFileIndex: 0,
+    });
+    expect(getStartupNavigationAction(0, 1, null, 'custom:formFill' as WorkbenchType)).toEqual({
+      workbench: 'viewer',
+      activeFileIndex: 0,
+    });
+
+    // 0→N (N>1) always goes to fileEditor
+    expect(getStartupNavigationAction(0, 3, null, 'viewer' as WorkbenchType)).toEqual({
+      workbench: 'fileEditor',
+    });
+    expect(getStartupNavigationAction(0, 3, null, 'custom:myTool' as WorkbenchType)).toEqual({
+      workbench: 'fileEditor',
+    });
+  });
+});
@@ -0,0 +1,49 @@
+import type { WorkbenchType } from '@app/types/workbench';
+
+export type StartupWorkbench = 'viewer' | 'fileEditor';
+
+export interface StartupNavigationAction {
+  workbench: StartupWorkbench;
+  activeFileIndex?: number;
+}
+
+export function getStartupNavigationAction(
+  previousFileCount: number,
+  currentFileCount: number,
+  selectedToolKey: string | null,
+  currentWorkbench: WorkbenchType
+): StartupNavigationAction | null {
+  console.log('[homePageNavigation] Called with:', {
+    previousFileCount,
+    currentFileCount,
+    selectedToolKey,
+    currentWorkbench,
+  });
+
+  // pdfTextEditor handles its own empty state
+  if (selectedToolKey === 'pdfTextEditor') {
+    console.log('[homePageNavigation] pdfTextEditor detected, returning null');
+    return null;
+  }
+
+  // Only handle transitions from empty (0 files) to some files
+  if (previousFileCount !== 0) {
+    console.log('[homePageNavigation] Not a 0→N transition, returning null');
+    return null;
+  }
+
+  // 0→1: Go to viewer to view the single file
+  if (currentFileCount === 1) {
+    console.log('[homePageNavigation] 0→1 transition, returning viewer');
+    return { workbench: 'viewer', activeFileIndex: 0 };
+  }
+
+  // 0→N (N>1): Go to fileEditor to manage multiple files
+  if (currentFileCount > 1) {
+    console.log('[homePageNavigation] 0→N transition, returning fileEditor');
+    return { workbench: 'fileEditor' };
+  }
+
+  console.log('[homePageNavigation] Still at 0 files, returning null');
+  return null;
+}