gridpilot.gg/plans/state-management-consolidation-plan.md

State Management Consolidation Plan

Problem Analysis

Current Mess

The codebase has multiple competing state management solutions causing confusion and redundancy:

1. /apps/website/components/shared/state/ (The "New" Solution)

• StateContainer.tsx - Combined wrapper for all states (loading, error, empty, success)
• LoadingWrapper.tsx - 5 variants: spinner, skeleton, full-screen, inline, card
• ErrorDisplay.tsx - 4 variants: full-screen, inline, card, toast
• EmptyState.tsx - 3 variants + pre-configured states + illustrations
• ❌ Missing types file: ../types/state.types (deleted but still imported)

2. /apps/website/components/shared/ (Legacy Simple Components)

• EmptyState.tsx - Simple empty state (39 lines)
• LoadingState.tsx - Simple loading spinner (15 lines)

3. /apps/website/components/errors/ (Alternative Error Solutions)

• ErrorDisplay.tsx - API error focused (different API than shared/state)
• EnhancedErrorBoundary.tsx - React error boundary
• ApiErrorBoundary.tsx - API error boundary
• EnhancedFormError.tsx - Form error handling

4. Domain-Specific Solutions

• FeedEmptyState.tsx - Feed-specific empty state
• EmptyState.tsx in leagues - Different design system

Core Issues

1. Missing types file causing import errors in all state components
2. Multiple similar components with different APIs
3. Inconsistent naming patterns
4. Redundant functionality
5. No single source of truth
6. Mixed concerns between generic and domain-specific

Solution Strategy

Phase 1: Create Unified Types

Create apps/website/components/shared/state/types.ts with all type definitions:

• EmptyState types
• LoadingState types
• ErrorDisplay types
• StateContainer types
• Convenience prop types

Phase 2: Consolidate Components

Keep only the comprehensive solution in /apps/website/components/shared/state/:

• Update imports to use new types file
• Ensure all components work with unified types
• Remove any redundant internal type definitions

Phase 3: Remove Redundant Files

Delete:

• /apps/website/components/shared/EmptyState.tsx (legacy)
• /apps/website/components/shared/LoadingState.tsx (legacy)
• Keep domain-specific ones if they serve unique purposes

Phase 4: Update All Imports

Find and update all imports across the codebase to use the consolidated solution.

Detailed Implementation

Step 1: Create Types File

File: apps/website/components/shared/state/types.ts

// All type definitions for state management
// EmptyState, LoadingWrapper, ErrorDisplay, StateContainer props
// Plus convenience types

Step 2: Update State Components

Files to update:

• EmptyState.tsx - Import from ./types.ts
• LoadingWrapper.tsx - Import from ./types.ts
• ErrorDisplay.tsx - Import from ./types.ts
• StateContainer.tsx - Import from ./types.ts

Step 3: Remove Legacy Files

Delete:

• apps/website/components/shared/EmptyState.tsx
• apps/website/components/shared/LoadingState.tsx

Step 4: Update External Imports

Search for: from '@/components/shared/EmptyState' or from '@/components/shared/LoadingState' Replace with: from '@/components/shared/state/EmptyState' or from '@/components/shared/state/LoadingWrapper'

Files to Modify

Create:

1. apps/website/components/shared/state/types.ts

Update:

1. apps/website/components/shared/state/EmptyState.tsx
2. apps/website/components/shared/state/LoadingWrapper.tsx
3. apps/website/components/shared/state/ErrorDisplay.tsx
4. apps/website/components/shared/state/StateContainer.tsx

Delete:

1. apps/website/components/shared/EmptyState.tsx
2. apps/website/components/shared/LoadingState.tsx

Update Imports in:

• Multiple app pages and templates
• Components that use the old paths

Expected Benefits

1. ✅ Single source of truth for state types
2. ✅ Consistent API across all state components
3. ✅ No import errors
4. ✅ Reduced file count and complexity
5. ✅ Better maintainability
6. ✅ Clear separation between generic and domain-specific solutions