Drag-and-Drop Dashboard Implementation Guide

This document presents a complete low-level design for implementing a drag-and-drop dashboard system, detailing component structure, state management patterns, and optimization techniques for high-performance UI interactions.

1. Problem Statement & Requirements

Clarifying questions

1. What target browsers/devices are we supporting? (e.g., mobile touch support, IE11 compatibility)
2. Do we need real-time collaboration or is this a single-user dashboard?
3. Should the drag-and-drop support persistence across sessions (localStorage, backend sync)?
4. What's the expected data volume and number of dashboard items?
5. Do we need to support keyboard navigation and screen readers for accessibility compliance?
6. Will this dashboard be part of a larger application with existing i18n or design system?
7. Are there specific performance constraints (e.g., < 100ms drag feedback, < 2s to render all items)?

Functional requirements

• Users can drag dashboard widgets between positions in a grid layout
• Widgets can be resized by dragging edges (horizontal/vertical)
• Dashboard items can be reordered within the same grid row/column
• Drag operations should provide visual feedback (ghost element, drop targets)
• Widgets can be added dynamically to the dashboard
• Widgets can be removed from the dashboard
• Dashboard should persist user's widget arrangement across sessions (if needed)
• Support for multi-column grid layout with configurable breakpoints

Non-functional requirements

• Performance: Drag operations must maintain 60fps, with <50ms latency for drop target calculations
• Accessibility: Full keyboard navigation support, ARIA roles, screen reader compatibility
• Scalability: Support up to 100 dashboard items with smooth interactions
• Responsiveness: Grid layout should adapt to different screen sizes (mobile, tablet, desktop)
• Reliability: Drag operations must be resilient to browser context changes (tab switching, window resizing)

Constraints and assumptions

• Dashboard items are represented as React components with fixed dimensions
• Drag-and-drop is implemented using HTML5 native drag events (not external libraries)
• No external state management system is available for this feature
• The dashboard will be part of a larger application with existing routing and auth systems
• All widget content is assumed to be safe for display (no XSS concerns in this scope)

Out of scope

• Multi-user collaborative editing or real-time synchronization
• Widget configuration UI (e.g., setting widget properties)
• Dashboard themes or custom styling beyond grid layout
• Server-side persistence of dashboard state (will be handled by backend integration)
• Complex animations or physics-based drag interactions
• Touch device support beyond basic drag-and-drop (mobile touch events)

2. Component Architecture

graph TD
    A[Dashboard] --> B[DashboardLayout]
    A --> C[WidgetContainer]
    B --> D[WidgetGrid]
    B --> E[Widget]
    C --> F[WidgetCard]
    D --> G[DraggableWidget]
    E --> H[WidgetHeader]
    E --> I[WidgetContent]
    G --> J[DragHandle]
    G --> K[WidgetPlaceholder]
    
    classDef smart fill:#4CAF50,stroke:#333,color:white;
    classDef dumb fill:#2196F3,stroke:#333,color:white;
    
    class A,B,C,D,E,G,H,I,J,K smart
    class F dumb

Component Tree Breakdown

Smart Components (Container/Logic):

• Dashboard - Main container managing dashboard-wide state and layout
• DashboardLayout - Handles grid layout and widget positioning logic
• WidgetContainer - Manages widget lifecycle and drag operations
• DraggableWidget - Implements drag-and-drop behavior with reordering

Dumb Components (Presentational):

• WidgetCard - Renders individual widget content with consistent styling
• WidgetHeader - Displays widget title and action buttons
• WidgetContent - Renders widget-specific content
• DragHandle - Visual element for initiating drag operations
• WidgetPlaceholder - Visual indicator for drop targets

TypeScript Props Contracts

// Dashboard Component
interface DashboardProps {
  widgets: Widget[];
  onWidgetReorder: (newOrder: string[]) => void;
  onWidgetAdd: (widgetType: WidgetType) => void;
  onWidgetRemove: (widgetId: string) => void;
}

// DraggableWidget Component
interface DraggableWidgetProps {
  widget: Widget;
  index: number;
  isDragging: boolean;
  onDragStart: (e: React.DragEvent, widgetId: string) => void;
  onDragEnd: (e: React.DragEvent) => void;
  onDrop: (e: React.DragEvent, targetId: string) => void;
  onDragOver: (e: React.DragEvent, targetId: string) => void;
}

// WidgetCard Component
interface WidgetCardProps {
  widget: Widget;
  isDragging?: boolean;
  onRemove?: (widgetId: string) => void;
  onEdit?: (widgetId: string) => void;
}

UI State Machine

stateDiagram-v2
    [*] --> Idle
    Idle --> Dragging : dragStart
    Dragging --> Dragging : dragOver
    Dragging --> Idle : dragEnd
    Dragging --> Dropping : drop
    Dropping --> Idle : dropComplete
    Idle --> Reordering : reorderStart
    Reordering --> Reordering : reorderInProgress
    Reordering --> Idle : reorderComplete

Component Responsibilities

Dashboard:

• Main entry point for dashboard view
• Manages overall widget collection and reordering logic
• Handles widget creation and deletion

DashboardLayout:

• Implements grid-based layout system
• Manages widget positioning within grid
• Handles drag-and-drop zone boundaries

WidgetContainer:

• Wraps individual widget rendering
• Manages widget lifecycle and state
• Handles drag operation state transitions

DraggableWidget:

• Implements HTML5 Drag and Drop API
• Handles drag start, end, and drop events
• Manages visual feedback during drag operations

Reusability Decisions

The component architecture prioritizes reusability through:

• Component composition over inheritance
• Consistent props contracts for predictable interactions
• Modular widget structure that can be extended with custom content types
• Visual separation between drag behavior and presentation logic

Component Lifecycle Considerations

1. Mounting: Widgets initialize with proper drag state tracking
2. Updating: Reordering updates widget positions without full re-renders
3. Unmounting: Clean up drag event listeners to prevent memory leaks
4. Drag Events: Properly handle drag start/end for visual feedback and cleanup

The design accounts for:

• Drag state persistence across re-renders
• Efficient DOM updates during drag operations
• Proper event listener cleanup to prevent memory leaks
• Responsive layout adjustments during drag operations

3. State Management Design

Local state vs. global state decisions

For drag-and-drop dashboard, we need to distinguish between:

• Local state: Component-specific UI state (dragging indicator, hover states, temporary reorder positions)
• Global state: Dashboard configuration, widget metadata, and persisted layout data

The drag-and-drop interaction is inherently local to the dashboard component, but the final state (widget positions and configurations) needs to be persisted globally.

State management approach

I'll use Zustand as the state management solution because:

1. It provides a clean, minimal API that's easy to reason about
2. Better developer experience than Redux Toolkit for smaller-scale applications
3. Excellent TypeScript support with type inference
4. No boilerplate or complex middleware setup needed
5. Easy to integrate with React Query for server state

State shape and normalization strategy

// Normalized state structure
interface Widget {
  id: string;
  type: 'chart' | 'table' | 'text' | 'image';
  title: string;
  content: any;
  position: { x: number; y: number; width: number; height: number };
  config?: WidgetConfig;
}

interface DashboardState {
  widgets: Record<string, Widget>;
  widgetOrder: string[];
  isDragging: boolean;
  draggedWidgetId: string | null;
  dragOverWidgetId: string | null;
  layoutVersion: number;
}

interface WidgetConfig {
  refreshInterval?: number;
  showLegend?: boolean;
  colorScheme?: string;
}

Server state vs. client state separation

• Client state: Current drag operations, temporary reorder positions, UI feedback states
• Server state: Persisted dashboard configurations, widget data, user preferences

Cache invalidation strategy

When a widget is reordered or added:

1. Update local dashboard state immediately (optimistic)
2. Send update to backend with debounce (500ms)
3. On successful response, increment layoutVersion
4. On failure, revert to previous state and show error

Optimistic updates design

For reorder operations:

1. Immediately update UI with new widget positions
2. Send to backend asynchronously
3. If backend fails, rollback to previous state and show error toast

Critical-path hook implementation

import { create } from 'zustand';
import { persist } from 'zustand/middleware';

interface Widget {
  id: string;
  type: 'chart' | 'table' | 'text' | 'image';
  title: string;
  content: any;
  position: { x: number; y: number; width: number; height: number };
  config?: WidgetConfig;
}

interface DashboardState {
  widgets: Record<string, Widget>;
  widgetOrder: string[];
  isDragging: boolean;
  draggedWidgetId: string | null;
  dragOverWidgetId: string | null;
  layoutVersion: number;
  // Actions
  addWidget: (widget: Widget) => void;
  removeWidget: (id: string) => void;
  updateWidgetPosition: (id: string, position: Widget['position']) => void;
  reorderWidgets: (newOrder: string[]) => void;
  startDrag: (id: string) => void;
  endDrag: () => void;
  setDragOver: (id: string | null) => void;
  saveLayout: () => Promise<void>;
}

const useDashboardStore = create<DashboardState>()(
  persist(
    (set, get) => ({
      widgets: {},
      widgetOrder: [],
      isDragging: false,
      draggedWidgetId: null,
      dragOverWidgetId: null,
      layoutVersion: 0,

      addWidget: (widget) => {
        set((state) => ({
          widgets: { ...state.widgets, [widget.id]: widget },
          widgetOrder: [...state.widgetOrder, widget.id],
        }));
      },

      removeWidget: (id) => {
        set((state) => {
          const widgets = { ...state.widgets };
          delete widgets[id];
          const newOrder = state.widgetOrder.filter((widgetId) => widgetId !== id);
          return {
            widgets,
            widgetOrder: newOrder,
          };
        });
      },

      updateWidgetPosition: (id, position) => {
        set((state) => ({
          widgets: {
            ...state.widgets,
            [id]: {
              ...state.widgets[id],
              position,
            },
          },
        }));
      },

      reorderWidgets: (newOrder) => {
        set((state) => ({
          widgetOrder: newOrder,
          layoutVersion: state.layoutVersion + 1,
        }));
      },

      startDrag: (id) => {
        set({
          isDragging: true,
          draggedWidgetId: id,
        });
      },

      endDrag: () => {
        set({
          isDragging: false,
          draggedWidgetId: null,
          dragOverWidgetId: null,
        });
      },

      setDragOver: (id) => {
        set({ dragOverWidgetId: id });
      },

      saveLayout: async () => {
        const state = get();
        try {
          // In a real app, this would be an API call
          await fetch('/api/dashboard/layout', {
            method: 'PUT',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
              widgets: Object.values(state.widgets),
              order: state.widgetOrder,
            }),
          });
        } catch (error) {
          console.error('Failed to save layout:', error);
          // In a real app, we'd show an error toast here
        }
      },
    }),
    {
      name: 'dashboard-storage',
      partialize: (state) => ({
        widgets: state.widgets,
        widgetOrder: state.widgetOrder,
      }),
    }
  )
);

// Custom hook for drag-and-drop operations
export const useDragAndDrop = () => {
  const {
    widgets,
    widgetOrder,
    isDragging,
    draggedWidgetId,
    dragOverWidgetId,
    updateWidgetPosition,
    reorderWidgets,
    startDrag,
    endDrag,
    setDragOver,
  } = useDashboardStore();

  const handleDragStart = (id: string) => {
    startDrag(id);
  };

  const handleDragEnd = () => {
    endDrag();
  };

  const handleDragOver = (id: string) => {
    setDragOver(id);
  };

  const handleDrop = (targetId: string) => {
    if (!draggedWidgetId || draggedWidgetId === targetId) {
      endDrag();
      return;
    }

    const draggedIndex = widgetOrder.indexOf(draggedWidgetId);
    const targetIndex = widgetOrder.indexOf(targetId);

    if (draggedIndex === -1 || targetIndex === -1) {
      endDrag();
      return;
    }

    const newOrder = [...widgetOrder];
    newOrder.splice(draggedIndex, 1);
    newOrder.splice(targetIndex, 0, draggedWidgetId);

    reorderWidgets(newOrder);
    endDrag();
  };

  return {
    widgets,
    widgetOrder,
    isDragging,
    draggedWidgetId,
    dragOverWidgetId,
    handleDragStart,
    handleDragEnd,
    handleDragOver,
    handleDrop,
  };
};

The hook returns a clean API for drag-and-drop operations while maintaining all the necessary state internally. The use of Zustand provides excellent performance characteristics with minimal re-renders, and the persistence middleware ensures that dashboard layouts survive page refreshes. The optimistic update pattern provides a smooth user experience while maintaining consistency with backend state.

4. Routing & Navigation

Route Structure and Hierarchy

graph TD
    A[Root] --> B[Dashboard Layout]
    B --> C[Dashboard Home]
    B --> D[Dashboard Settings]
    B --> E[Dashboard Analytics]

The dashboard feature will be structured under a /dashboard route hierarchy with the following structure:

• /dashboard - Main dashboard layout component
• /dashboard/home - Primary dashboard view with draggable widgets
• /dashboard/settings - Configuration and customization settings
• /dashboard/analytics - Analytics and reporting views

Code Splitting Strategy

Route-based code splitting will be implemented using React.lazy and Suspense for optimal bundle loading:

1. Dashboard Home Route (/dashboard/home) - Split into:

   • Main dashboard container (core)
   • Widget components (lazy-loaded)
   • Drag-and-drop utilities (lazy-loaded)

2. Dashboard Settings Route (/dashboard/settings) - Split into:

   • Configuration components (lazy-loaded)
   • Theme customization (lazy-loaded)

3. Dashboard Analytics Route (/dashboard/analytics) - Split into:

   • Analytics components (lazy-loaded)
   • Charting libraries (lazy-loaded)

The dashboard home route will be preloaded as it's the most frequently accessed, while other routes will load on demand to reduce initial bundle size.

Navigation Guards and Authentication Flows

Authentication guards will be implemented using React Router's useNavigate hook and protected route wrappers:

// ProtectedRoute.tsx
const ProtectedRoute: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const { isAuthenticated, loading } = useAuth();
  
  if (loading) return <LoadingSpinner />;
  if (!isAuthenticated) return <Navigate to="/login" replace />;
  
  return children;
};

// DashboardLayout.tsx
const DashboardLayout: React.FC = () => {
  const navigate = useNavigate();
  
  useEffect(() => {
    const handleAuthChange = () => {
      if (!isAuthenticated) {
        navigate('/login', { replace: true });
      }
    };
    
    // Subscribe to auth state changes
    const unsubscribe = onAuthStateChanged(auth, handleAuthChange);
    
    return () => unsubscribe();
  }, [isAuthenticated, navigate]);
  
  return (
    <div className="dashboard-layout">
      <Header />
      <main className="dashboard-main">
        <Outlet />
      </main>
    </div>
  );
};

Deep Linking Support and URL Parameter Design

Deep linking will support:

• /dashboard/home?widget=analytics&theme=dark
• /dashboard/settings?tab=widgets

URL parameters will be managed through React Router's useSearchParams hook:

// DashboardHome.tsx
const DashboardHome: React.FC = () => {
  const [searchParams, setSearchParams] = useSearchParams();
  
  const widgetParam = searchParams.get('widget');
  const themeParam = searchParams.get('theme');
  
  useEffect(() => {
    if (widgetParam) {
      // Load specific widget
      loadWidget(widgetParam);
    }
    
    if (themeParam) {
      // Apply theme
      applyTheme(themeParam);
    }
  }, [widgetParam, themeParam]);
  
  const handleWidgetChange = (widgetId: string) => {
    setSearchParams({ widget: widgetId });
  };
  
  return (
    <div className="dashboard-container">
      {/* Widget grid with drag-and-drop */}
    </div>
  );
};

Browser History Management and Scroll Restoration

Scroll restoration will be handled through React Router's built-in scroll restoration:

// App.tsx
const App: React.FC = () => {
  return (
    <BrowserRouter>
      <ScrollRestoration />
      <Routes>
        <Route path="/dashboard" element={<DashboardLayout />}>
          <Route index element={<DashboardHome />} />
          <Route path="settings" element={<DashboardSettings />} />
          <Route path="analytics" element={<DashboardAnalytics />} />
        </Route>
      </Routes>
    </BrowserRouter>
  );
};

// Custom scroll restoration for dashboard-specific needs
const DashboardScrollRestoration: React.FC = () => {
  const location = useLocation();
  
  useEffect(() => {
    // Preserve scroll position for dashboard view
    const savedPosition = sessionStorage.getItem(`scroll-position-${location.pathname}`);
    
    if (savedPosition) {
      window.scrollTo(0, parseInt(savedPosition));
    } else {
      window.scrollTo(0, 0);
    }
    
    // Save scroll position when user scrolls
    const handleScroll = () => {
      sessionStorage.setItem(`scroll-position-${location.pathname}`, window.scrollY.toString());
    };
    
    window.addEventListener('scroll', handleScroll);
    
    return () => {
      window.removeEventListener('scroll', handleScroll);
    };
  }, [location.pathname]);
  
  return null;
};

The scroll restoration strategy will:

1. Use React Router's built-in scroll restoration as default
2. Implement custom session storage for dashboard-specific scroll positions
3. Preserve scroll position when navigating between dashboard sub-routes
4. Reset to top on fresh route loads

5. API Integration Layer

API client design pattern

We'll implement a centralized Axios instance with request/response interceptors to handle authentication, error handling, and data transformation consistently across the application.

// api/client.ts
import axios, { AxiosInstance } from 'axios';

const apiClient: AxiosInstance = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_BASE_URL || 'https://api.example.com',
  timeout: 10000,
  headers: {
    'Content-Type': 'application/json',
  },
});

// Request interceptor for adding auth token
apiClient.interceptors.request.use(
  (config) => {
    const token = localStorage.getItem('authToken');
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error)
);

// Response interceptor for handling errors
apiClient.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      // Handle token expiration
      localStorage.removeItem('authToken');
      window.location.href = '/login';
    }
    return Promise.reject(error);
  }
);

export default apiClient;

Request/response interceptors

Authentication token injection, response normalization, and error transformation:

// api/interceptors.ts
import { AxiosError, AxiosResponse } from 'axios';
import apiClient from './client';

// Response normalization to standardize error format
apiClient.interceptors.response.use(
  (response: AxiosResponse) => {
    return {
      data: response.data,
      status: response.status,
      headers: response.headers,
    };
  },
  (error: AxiosError) => {
    const normalizedError = {
      message: error.message,
      status: error.response?.status || 500,
      code: error.code,
      details: error.response?.data || {},
    };
    
    return Promise.reject(normalizedError);
  }
);

// Retry strategy for transient errors
apiClient.interceptors.request.use(
  (config) => {
    config.retry = config.retry || 0;
    return config;
  },
  (error) => Promise.reject(error)
);

apiClient.interceptors.response.use(
  (response) => response,
  async (error) => {
    const config = error.config;
    if (config && error.response?.status >= 500 && config.retry < 3) {
      config.retry += 1;
      return new Promise((resolve) => setTimeout(() => resolve(apiClient(config)), 1000));
    }
    return Promise.reject(error);
  }
);

Error handling and retry strategy

Comprehensive error handling with retry logic for transient failures:

// api/errorHandler.ts
export interface ApiError {
  message: string;
  status: number;
  code?: string;
  details?: any;
}

export const handleApiError = (error: ApiError): void => {
  if (error.status === 401) {
    // Redirect to login page
    window.location.href = '/login';
  } else if (error.status === 403) {
    // Handle forbidden access
    console.warn('Access denied:', error.message);
  } else if (error.status >= 500) {
    // Log server errors for monitoring
    console.error('Server error:', error);
  } else {
    // Handle client errors
    console.error('API Error:', error);
  }
};

// Retryable API call function
export const retryableApiCall = async <T>(
  apiCall: () => Promise<T>,
  retries = 3,
  delay = 1000
): Promise<T> => {
  for (let i = 0; i < retries; i++) {
    try {
      return await apiCall();
    } catch (error) {
      if (i === retries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, delay * Math.pow(2, i)));
    }
  }
  throw new Error('Max retries exceeded');
};

Loading, error, and empty states design

Standardized loading, error, and empty state patterns:

// components/LoadingState.tsx
import { Spinner } from './Spinner';

interface LoadingStateProps {
  message?: string;
}

export const LoadingState: React.FC<LoadingStateProps> = ({ message = "Loading..." }) => (
  <div className="flex items-center justify-center py-12">
    <Spinner />
    <span className="ml-3">{message}</span>
  </div>
);

// components/ErrorState.tsx
interface ErrorStateProps {
  error: ApiError;
  onRetry?: () => void;
}

export const ErrorState: React.FC<ErrorStateProps> = ({ error, onRetry }) => (
  <div className="flex flex-col items-center justify-center py-12 text-center">
    <div className="text-red-500 mb-4">⚠️</div>
    <h3 className="text-lg font-medium text-gray-900">Something went wrong</h3>
    <p className="mt-1 text-sm text-gray-500">{error.message}</p>
    {onRetry && (
      <button
        onClick={onRetry}
        className="mt-4 px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700"
      >
        Retry
      </button>
    )}
  </div>
);

// components/EmptyState.tsx
interface EmptyStateProps {
  title: string;
  description?: string;
  actionText?: string;
  onAction?: () => void;
}

export const EmptyState: React.FC<EmptyStateProps> = ({ 
  title, 
  description,
  actionText,
  onAction 
}) => (
  <div className="flex flex-col items-center justify-center py-12 text-center">
    <div className="text-gray-400 mb-4">📭</div>
    <h3 className="text-lg font-medium text-gray-900">{title}</h3>
    {description && <p className="mt-1 text-sm text-gray-500">{description}</p>}
    {onAction && actionText && (
      <button
        onClick={onAction}
        className="mt-4 px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700"
      >
        {actionText}
      </button>
    )}
  </div>
);

Data fetching strategy

Client-side rendering with React Query for optimal data fetching and caching:

// hooks/useDashboardData.ts
import { useQuery, useMutation, QueryClient } from '@tanstack/react-query';
import apiClient from '../api/client';

// Dashboard data types
export interface Widget {
  id: string;
  type: 'chart' | 'table' | 'list';
  title: string;
  content: any;
  position: { x: number; y: number; width: number; height: number };
}

export interface Dashboard {
  id: string;
  name: string;
  widgets: Widget[];
  createdAt: string;
  updatedAt: string;
}

// Query keys for React Query
const DASHBOARD_QUERY_KEY = 'dashboard';
const WIDGETS_QUERY_KEY = 'widgets';

// Fetch dashboard data
export const fetchDashboard = async (dashboardId: string): Promise<Dashboard> => {
  const response = await apiClient.get(`/dashboards/${dashboardId}`);
  return response.data;
};

// Update widget positions
export const updateWidgetPositions = async (dashboardId: string, widgets: Widget[]) => {
  const response = await apiClient.put(`/dashboards/${dashboardId}/widgets`, { widgets });
  return response.data;
};

// Dashboard data hook
export const useDashboardData = (dashboardId: string) => {
  return useQuery<Dashboard, ApiError>({
    queryKey: [DASHBOARD_QUERY_KEY, dashboardId],
    queryFn: () => fetchDashboard(dashboardId),
    staleTime: 5 * 60 * 1000, // 5 minutes
    cacheTime: 10 * 60 * 1000, // 10 minutes
  });
};

// Widget position update mutation
export const useUpdateWidgetPositions = (dashboardId: string) => {
  const queryClient = new QueryClient();
  
  return useMutation<Dashboard, ApiError, Widget[]>({
    mutationFn: (widgets) => updateWidgetPositions(dashboardId, widgets),
    onSuccess: (data) => {
      // Invalidate and refetch dashboard data
      queryClient.invalidateQueries([DASHBOARD_QUERY_KEY, dashboardId]);
    },
    onError: (error) => {
      console.error('Failed to update widget positions:', error);
    },
  });
};

API response transformation layer

DTO to domain model mapping:

// api/transformers.ts
import { Widget, Dashboard } from '../hooks/useDashboardData';

// Transform API response to domain model
export const transformWidgetFromApi = (apiWidget: any): Widget => ({
  id: apiWidget.id,
  type: apiWidget.type,
  title: apiWidget.title,
  content: apiWidget.content,
  position: {
    x: apiWidget.position.x,
    y: apiWidget.position.y,
    width: apiWidget.position.width,
    height: apiWidget.position.height,
  },
});

export const transformDashboardFromApi = (apiDashboard: any): Dashboard => ({
  id: apiDashboard.id,
  name: apiDashboard.name,
  widgets: apiDashboard.widgets.map(transformWidgetFromApi),
  createdAt: apiDashboard.created_at,
  updatedAt: apiDashboard.updated_at,
});

// Transform domain model to API payload
export const transformWidgetToApi = (widget: Widget): any => ({
  id: widget.id,
  type: widget.type,
  title: widget.title,
  content: widget.content,
  position: {
    x: widget.position.x,
    y: widget.position.y,
    width: widget.position.width,
    height: widget.position.height,
  },
});

Sequence diagram for primary data flows

sequenceDiagram
    participant U as User
    participant C as Dashboard Component
    participant Q as React Query
    participant A as API Client
    participant S as Server

    U->>C: Request dashboard data
    C->>Q: Fetch dashboard query
    Q->>A: Make GET /dashboards/:id request
    A->>S: Send request to server
    S-->>A: Return dashboard data
    A-->>Q: Response with data
    Q-->>C: Provide dashboard data
    C->>U: Render dashboard with widgets

    U->>C: Drag and drop widget
    C->>Q: Update widget positions mutation
    Q->>A: Make PUT /dashboards/:id/widgets request
    A->>S: Send updated widget positions
    S-->>A: Return success response
    A-->>Q: Response with updated dashboard
    Q-->>C: Invalidate and refetch data
    C->>U: Update UI with new widget positions

6. Performance Design

Core Web Vitals Targets

• Largest Contentful Paint (LCP): <2.5s for all dashboard layouts
• Interaction to Next Paint (INP): <200ms for drag interactions and widget reordering
• Cumulative Layout Shift (CLS): <0.1 for all drag operations and widget repositioning

Bundle Size Budget per Route

• Dashboard route: <50KB (excluding vendor libraries)
• Drag-and-drop utilities: <15KB
• Widget rendering components: <20KB total

Critical Rendering Path Optimization

// Critical CSS extraction and inlining for drag handles
const criticalDragStyles = `
  .drag-handle {
    cursor: move;
    user-select: none;
    -webkit-user-drag: none;
  }
  .widget-dragging {
    opacity: 0.7;
    z-index: 1000;
  }
`;

Image Optimization Strategy

• All widget images use WebP format with fallbacks for older browsers
• Images lazy-loaded with loading="lazy" attribute
• Responsive image sizes using srcset for different viewport widths
• Placeholder loading with skeleton states during image fetch

Font Loading Strategy

/* Critical font subset loading */
@font-face {
  font-family: 'Inter';
  src: url('/fonts/inter-cyrillic-400.woff2') format('woff2');
  font-display: swap;
  unicode-range: U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;
}

/* Non-critical fonts loaded after initial render */
@font-face {
  font-family: 'Inter';
  src: url('/fonts/inter-400.woff2') format('woff2');
  font-display: swap;
}

Memoization Strategy

// Widget component with proper memoization
const Widget = React.memo(({ widget, onDragStart }: WidgetProps) => {
  const handleDragStart = useCallback((e: React.DragEvent) => {
    onDragStart(widget.id, e);
  }, [widget.id, onDragStart]);

  return (
    <div 
      draggable
      onDragStart={handleDragStart}
      className="widget"
    >
      <WidgetContent widget={widget} />
    </div>
  );
});

// Memoize drag state calculations
const useDragState = () => {
  const [draggedWidget, setDraggedWidget] = useState<Widget | null>(null);
  const [dragOverIndex, setDragOverIndex] = useState<number | null>(null);

  const calculateDropPosition = useCallback((clientY: number, containerRect: DOMRect) => {
    // Optimized calculation without re-renders
    return Math.floor((clientY - containerRect.top) / 100);
  }, []);

  return {
    draggedWidget,
    dragOverIndex,
    calculateDropPosition
  };
};

Virtualization for Large Lists

For dashboards with >50 widgets, implement virtualization:

import { FixedSizeList as List } from 'react-window';

const VirtualizedWidgetList = ({ widgets, onDragStart }: VirtualizedWidgetProps) => {
  const Row = ({ index, style }: { index: number; style: React.CSSProperties }) => (
    <div style={style}>
      <Widget 
        widget={widgets[index]} 
        onDragStart={onDragStart} 
      />
    </div>
  );

  return (
    <List
      height={600}
      itemCount={widgets.length}
      itemSize={100}
      width="100%"
    >
      {Row}
    </List>
  );
};

Prefetching and Preloading Strategy

// Preload critical widget assets during dashboard load
const preloadWidgetAssets = (widgets: Widget[]) => {
  widgets.forEach(widget => {
    if (widget.image) {
      const img = new Image();
      img.src = widget.image;
    }
  });
};

// Preload drag handle icons and cursor assets
const preloadDragAssets = () => {
  const dragIcons = [
    '/icons/drag-handle.svg',
    '/cursor/grab-cursor.png'
  ];
  
  dragIcons.forEach(src => {
    const link = document.createElement('link');
    link.rel = 'prefetch';
    link.href = src;
    document.head.appendChild(link);
  });
};

Performance Monitoring

// Track drag interaction performance
const useDragPerformance = () => {
  const [performanceMetrics, setPerformanceMetrics] = useState({
    dragStartLatency: 0,
    dropRepositionTime: 0,
    layoutShiftScore: 0
  });

  const measureDragPerformance = (start: number, end: number) => {
    const latency = end - start;
    setPerformanceMetrics(prev => ({
      ...prev,
      dragStartLatency: latency
    }));
  };

  return { performanceMetrics, measureDragPerformance };
};

7. Error Handling & Resilience

Error Boundary Placement Strategy

Error boundaries should be strategically placed to prevent cascading failures while maintaining user experience. For a drag-and-drop dashboard, we'll implement error boundaries at multiple levels:

• Dashboard Level: Catches errors in the entire dashboard rendering
• Widget Level: Isolates widget-specific failures (e.g., if one widget crashes, others remain functional)
• Drag-and-Drop Context: Handles errors in drag operations and state management

graph TD
    A[Dashboard] --> B[WidgetContainer]
    A --> C[DragAndDropContext]
    B --> D[Widget1]
    B --> E[Widget2]
    D --> F[Widget1ErrorBoundary]
    E --> G[Widget2ErrorBoundary]

Global Error Handler Design

A global error handler will capture unhandled errors and provide appropriate user feedback:

// ErrorBoundary.tsx
import React from 'react';

interface ErrorBoundaryState {
  hasError: boolean;
  error?: Error;
  errorInfo?: React.ErrorInfo;
}

class ErrorBoundary extends React.Component<
  { children: React.ReactNode },
  ErrorBoundaryState
> {
  constructor(props: { children: React.ReactNode }) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
    return { hasError: true, error };
  }

  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
    console.error('Dashboard Error:', error, errorInfo);
    // Report to monitoring service
    this.reportError(error, errorInfo);
  }

  private reportError = (error: Error, errorInfo: React.ErrorInfo) => {
    // Send to Sentry or similar monitoring service
    if (window.Sentry) {
      window.Sentry.captureException(error, {
        contexts: { react: errorInfo },
      });
    }
  };

  render() {
    if (this.state.hasError) {
      return (
        <div className="error-container">
          <h2>Something went wrong</h2>
          <p>We're sorry, but an error occurred while rendering the dashboard.</p>
          <button onClick={() => window.location.reload()}>
            Reload Dashboard
          </button>
        </div>
      );
    }

    return this.props.children;
  }
}

Offline / Network Failure Handling

The dashboard should gracefully handle network failures during drag operations:

// useDragDrop.ts
import { useState, useEffect } from 'react';

interface DragState {
  isDragging: boolean;
  draggedItem?: DashboardItem;
  error?: string;
}

export const useDragDrop = () => {
  const [dragState, setDragState] = useState<DragState>({
    isDragging: false,
  });
  const [offline, setOffline] = useState(false);

  useEffect(() => {
    const handleOnline = () => setOffline(false);
    const handleOffline = () => setOffline(true);

    window.addEventListener('online', handleOnline);
    window.addEventListener('offline', handleOffline);

    return () => {
      window.removeEventListener('online', handleOnline);
      window.removeEventListener('offline', handleOffline);
    };
  }, []);

  const handleDragStart = (item: DashboardItem) => {
    if (offline) {
      setDragState({
        isDragging: false,
        error: 'Cannot drag items when offline',
      });
      return;
    }

    setDragState({
      isDragging: true,
      draggedItem: item,
    });
  };

  const handleDrop = async (targetPosition: Position) => {
    if (offline) {
      setDragState({
        isDragging: false,
        error: 'Cannot save changes when offline',
      });
      return;
    }

    try {
      await saveDashboardLayout(targetPosition);
      setDragState({
        isDragging: false,
      });
    } catch (error) {
      setDragState({
        isDragging: false,
        error: 'Failed to save layout. Changes may be lost.',
      });
    }
  };

  return {
    ...dragState,
    offline,
  };
};

Graceful Degradation Patterns

When drag-and-drop functionality is unavailable, provide alternative interaction methods:

// Dashboard.tsx
const Dashboard = () => {
  const [isDragSupported, setIsDragSupported] = useState(true);
  const [layoutMode, setLayoutMode] = useState<'drag' | 'manual'>('drag');
  
  useEffect(() => {
    // Check for drag support
    const supportsDrag = 'ondragstart' in document.createElement('div');
    setIsDragSupported(supportsDrag);
    
    if (!supportsDrag) {
      setLayoutMode('manual');
    }
  }, []);

  if (!isDragSupported) {
    return (
      <div className="dashboard-fallback">
        <p>Drag-and-drop is not supported in your browser.</p>
        <button onClick={() => setLayoutMode('manual')}>
          Switch to Manual Layout Mode
        </button>
      </div>
    );
  }

  return (
    <ErrorBoundary>
      <DragAndDropContext>
        {/* Dashboard content */}
      </DragAndDropContext>
    </ErrorBoundary>
  );
};

User Feedback on Errors

Implement clear error messaging with appropriate fallbacks:

// ErrorToast.tsx
import React from 'react';

interface ToastProps {
  message: string;
  type: 'error' | 'warning' | 'info';
  onClose: () => void;
}

const Toast = ({ message, type, onClose }: ToastProps) => {
  const bgColor = 
    type === 'error' ? 'bg-red-500' : 
    type === 'warning' ? 'bg-yellow-500' : 
    'bg-blue-500';

  return (
    <div className={`fixed bottom-4 right-4 p-4 rounded-lg text-white ${bgColor} animate-fadeIn`}>
      <div className="flex items-center">
        <span>{message}</span>
        <button 
          onClick={onClose}
          className="ml-4 text-white hover:text-gray-200"
        >
          ✕
        </button>
      </div>
    </div>
  );
};

// ErrorManager.tsx
import { useState } from 'react';

export const useErrorManager = () => {
  const [toasts, setToasts] = useState<{id: string, message: string, type: string}[]>([]);
  
  const addToast = (message: string, type: 'error' | 'warning' | 'info' = 'error') => {
    const id = Date.now().toString();
    setToasts(prev => [...prev, { id, message, type }]);
    
    // Auto-remove after 5 seconds
    setTimeout(() => {
      setToasts(prev => prev.filter(t => t.id !== id));
    }, 5000);
  };

  return { toasts, addToast };
};

Retry Strategy for Failed Operations

Implement retry logic with exponential backoff for drag-and-drop operations:

// useRetryableDrag.ts
import { useState, useCallback } from 'react';

interface RetryConfig {
  maxRetries?: number;
  baseDelay?: number;
}

const useRetryableDrag = (config: RetryConfig = {}) => {
  const { maxRetries = 3, baseDelay = 1000 } = config;
  const [retryCount, setRetryCount] = useState(0);
  const [lastError, setLastError] = useState<Error | null>(null);

  const retryOperation = useCallback(async <T>(
    operation: () => Promise<T>,
    operationName: string
  ): Promise<T | null> => {
    try {
      setLastError(null);
      return await operation();
    } catch (error) {
      if (retryCount < maxRetries) {
        setLastError(error as Error);
        const delay = baseDelay * Math.pow(2, retryCount);
        
        setTimeout(() => {
          setRetryCount(prev => prev + 1);
          // Retry operation with updated retry count
        }, delay);
        
        return null;
      }
      
      setLastError(error as Error);
      throw error;
    }
  }, [retryCount, maxRetries, baseDelay]);

  return {
    retryCount,
    lastError,
    retryOperation,
  };
};

Error Recovery and State Restoration

Implement dashboard state recovery from local storage:

// useDashboardPersistence.ts
import { useEffect, useState } from 'react';

interface DashboardState {
  items: DashboardItem[];
  layout: Layout;
}

export const useDashboardPersistence = () => {
  const [dashboardState, setDashboardState] = useState<DashboardState | null>(null);
  const [isRestoring, setIsRestoring] = useState(false);

  useEffect(() => {
    const restoreFromStorage = () => {
      setIsRestoring(true);
      try {
        const savedState = localStorage.getItem('dashboard-state');
        if (savedState) {
          const parsedState = JSON.parse(savedState);
          setDashboardState(parsedState);
        }
      } catch (error) {
        console.error('Failed to restore dashboard state:', error);
        // Fallback to default state
        setDashboardState(null);
      } finally {
        setIsRestoring(false);
      }
    };

    restoreFromStorage();
  }, []);

  const saveDashboardState = useCallback((state: DashboardState) => {
    try {
      localStorage.setItem('dashboard-state', JSON.stringify(state));
    } catch (error) {
      console.error('Failed to save dashboard state:', error);
      // Fallback to in-memory storage or notify user
    }
  }, []);

  return {
    dashboardState,
    isRestoring,
    saveDashboardState,
  };
};

8. Testing Strategy

Unit Testing Approach

Component Tests (70% of test coverage target):

• DashboardContainer: Test drag start, drag over, drop events with mock items
• WidgetCard: Verify drag handle rendering, widget content display, and state transitions
• WidgetPlaceholder: Test placeholder rendering with correct dimensions and drop zones
• DragDropContextProvider: Validate context provider wraps children correctly and provides proper values

Utility Tests (20% of test coverage target):

• dragAndDropUtils: Test position calculations, item reordering logic, and drop zone detection
• widgetUtils: Test widget type validation, default configuration generation, and state serialization

Test Coverage Targets:

• Components: 85% statement coverage, 75% branch coverage
• Utilities: 90% statement coverage, 85% branch coverage

// Example unit test for widget reordering logic
import { reorderWidgets } from './dragAndDropUtils';

describe('reorderWidgets', () => {
  const widgets = [
    { id: '1', type: 'chart', position: { x: 0, y: 0 } },
    { id: '2', type: 'table', position: { x: 1, y: 0 } },
    { id: '3', type: 'text', position: { x: 2, y: 0 } }
  ];

  it('should reorder widgets when dragging to new position', () => {
    const result = reorderWidgets(widgets, 0, 2);
    expect(result[0].id).toBe('2');
    expect(result[1].id).toBe('3');
    expect(result[2].id).toBe('1');
  });

  it('should handle edge case of dragging to same position', () => {
    const result = reorderWidgets(widgets, 0, 0);
    expect(result).toEqual(widgets);
  });
});

Integration Testing Strategy

Feature Integration Tests (15% of test coverage target):

• Full drag-and-drop flow: widget selection → drag → drop → state update
• Cross-widget type compatibility validation (e.g., chart can't be dropped on text)
• Multi-step drag operations with multiple widgets
• State persistence after drag operations (mocked API calls)

Testing Tools:

• React Testing Library for DOM interaction testing
• Jest for mocking and asynchronous operations
• MSW (Mock Service Worker) for API interaction mocking

E2E Testing Scope

Test Coverage:

• End-to-end drag-and-drop workflow from widget selection to placement
• Cross-browser compatibility testing (Chrome, Firefox, Safari)
• Responsive behavior testing across device sizes (mobile, tablet, desktop)
• Keyboard navigation support during drag operations

E2E Testing Tool:

• Playwright (preferred over Cypress due to better multi-browser support and faster execution)
• Test scenarios:
  • Drag widget from sidebar to dashboard
  • Reorder existing widgets via drag-and-drop
  • Drop widget outside dashboard bounds (should cancel operation)
  • Handle concurrent drag operations

Visual Regression Testing

Implementation:

• Percy (or similar visual testing tool) integrated into CI pipeline
• Test baseline screenshots for dashboard states:
  • Empty dashboard view
  • Dashboard with multiple widgets
  • Drag operation in progress (visual feedback)
  • Error states and validation messages

Accessibility Testing Automation

Tools:

• axe-core integrated into component tests
• Test for:
  • Proper ARIA roles and properties on draggable elements
  • Keyboard navigation support (Tab, Enter, Space)
  • Focus management during drag operations
  • Screen reader compatibility with drag state announcements

Test Coverage:

• ARIA role validation for draggable items
• Keyboard accessibility compliance
• Screen reader announcement testing

Test Data Strategy and Fixtures

Test Data Generation:

• Mock widget configurations with various types (chart, table, text)
• Multi-size dashboard layouts for responsive testing
• Edge case scenarios:
  • Empty dashboard state
  • Full dashboard with maximum widget count
  • Dashboard with invalid widget configurations

Fixtures:

• mockWidgets.ts: Various widget types with different dimensions and content
• mockDashboardState.ts: Complete dashboard configurations for integration tests
• mockDragEvents.ts: Simulated drag events with different parameters

// Example test data fixture
const mockWidgets = [
  {
    id: 'chart-1',
    type: 'chart',
    title: 'Sales Overview',
    content: { series: [], labels: [] },
    position: { x: 0, y: 0 },
    size: { width: 4, height: 3 }
  },
  {
    id: 'table-1',
    type: 'table',
    title: 'User Analytics',
    content: { headers: [], rows: [] },
    position: { x: 4, y: 0 },
    size: { width: 4, height: 3 }
  }
];

9. Accessibility (A11y)

WCAG 2.1 AA Compliance Checklist

The drag-and-drop dashboard must meet all Level AA success criteria:

• 1.1.1 Non-text Content: All draggables and drop zones have appropriate ARIA labels
• 1.3.1 Info and Relationships: Proper semantic HTML structure with role hierarchy
• 1.4.1 Use of Color: Sufficient contrast ratios (4.5:1) for drag states and drop targets
• 1.4.3 Contrast (Minimum): All interactive elements meet minimum contrast requirements
• 2.1.1 Keyboard: Full keyboard navigation support for all drag operations
• 2.4.1 Bypass Blocks: Skip links to dashboard content
• 3.1.1 Language: Language attributes for content localization
• 4.1.2 Name, Role, Value: All interactive elements have proper ARIA attributes

Keyboard Navigation Support

All drag-and-drop interactions must be fully operable via keyboard:

• Tab navigation: Moves through draggable items and drop zones in logical order
• Space/Enter: Activate drag mode for selected item
• Arrow keys: Navigate between items when in drag mode
• Escape: Cancel current drag operation
• Enter: Drop item at target location

Focus Management Strategy

Focus Trapping: When entering drag mode, focus is trapped within the dashboard container:

const handleDragStart = (e: React.DragEvent, item: DashboardItem) => {
  // Trap focus within dashboard container
  const dashboardContainer = document.getElementById('dashboard-container');
  if (dashboardContainer) {
    const focusableElements = dashboardContainer.querySelectorAll(
      'button, input, select, textarea, [tabindex]:not([tabindex="-1"])'
    );
    
    // Store original focus
    const originalFocus = document.activeElement;
    
    // Set focus to first draggable item
    const firstDraggable = focusableElements[0];
    if (firstDraggable) {
      (firstDraggable as HTMLElement).focus();
    }
    
    // Restore focus on drag end
    const restoreFocus = () => {
      if (originalFocus instanceof HTMLElement) {
        originalFocus.focus();
      }
    };
    
    // Cleanup on drag end
    e.dataTransfer.addEventListener('dragend', restoreFocus);
  }
};

Focus Restoration: When drag operations complete, focus returns to the original context.

ARIA Roles and Attributes Plan

// DashboardItem component with proper ARIA attributes
interface DashboardItemProps {
  id: string;
  title: string;
  type: 'widget' | 'chart' | 'table';
  position: { x: number; y: number };
  isDragging?: boolean;
  onDragStart: (e: React.DragEvent) => void;
  onDragEnd: () => void;
}

const DashboardItem: React.FC<DashboardItemProps> = ({
  id,
  title,
  type,
  position,
  isDragging = false,
  onDragStart,
  onDragEnd
}) => {
  return (
    <div
      role="article"
      aria-label={`Dashboard item: ${title}`}
      aria-describedby={`item-description-${id}`}
      draggable={true}
      onDragStart={onDragStart}
      onDragEnd={onDragEnd}
      className={`dashboard-item ${isDragging ? 'dragging' : ''}`}
      tabIndex={0}
      data-testid={`dashboard-item-${id}`}
    >
      <div className="item-header" role="heading" aria-level={2}>
        {title}
      </div>
      <div className="item-content">
        {/* Item content */}
      </div>
    </div>
  );
};

// Drop zone component
const DropZone: React.FC<{
  onDrop: (e: React.DragEvent) => void;
  onDragOver: (e: React.DragEvent) => void;
  isActive?: boolean;
}> = ({ onDrop, onDragOver, isActive = false }) => {
  return (
    <div
      role="region"
      aria-label={isActive ? "Active drop zone" : "Drop zone"}
      className={`drop-zone ${isActive ? 'active' : ''}`}
      onDrop={onDrop}
      onDragOver={onDragOver}
      onDragEnter={(e) => {
        e.preventDefault();
        e.dataTransfer.dropEffect = 'move';
      }}
      tabIndex={0}
    >
      {isActive ? (
        <div className="drop-zone-indicator">Drop here</div>
      ) : (
        <div className="drop-zone-placeholder">Drag items here</div>
      )}
    </div>
  );
};

Screen Reader Compatibility

• Live regions: Status updates for drag operations use aria-live="polite"
• Dynamic content changes: Updates to dashboard layout announce changes to screen readers
• Descriptive labels: All interactive elements have meaningful, descriptive labels

const DragStatusIndicator: React.FC<{
  status: 'idle' | 'dragging' | 'dropping';
  currentItem?: string;
}> = ({ status, currentItem }) => {
  const statusText = status === 'dragging' 
    ? `Dragging item: ${currentItem || 'unknown'}` 
    : status === 'dropping'
    ? `Dropping item: ${currentItem || 'unknown'}`
    : 'Ready to drag';

  return (
    <div 
      aria-live="polite" 
      aria-atomic="true"
      className="sr-only"
    >
      {statusText}
    </div>
  );
};

Keyboard Focus Indicators

Visual focus indicators must be clearly visible and accessible:

/* Ensure keyboard focus is visible */
.dashboard-item:focus {
  outline: 2px solid #007bff;
  outline-offset: 2px;
}

/* Ensure drop zones are keyboard accessible */
.drop-zone:focus {
  outline: 2px solid #28a745;
  outline-offset: 2px;
}

ARIA State Management

// Drag and drop state management for accessibility
const useDragDropAccessibility = () => {
  const [draggedItem, setDraggedItem] = useState<string | null>(null);
  const [dropTarget, setDropTarget] = useState<string | null>(null);

  const handleDragStart = (itemId: string) => {
    setDraggedItem(itemId);
    // Announce drag start to screen readers
    announceToScreenReader(`Dragging item ${itemId}`);
  };

  const handleDragEnd = () => {
    setDraggedItem(null);
    setDropTarget(null);
    // Announce drag completion
    announceToScreenReader('Drag operation completed');
  };

  const handleDragOver = (targetId: string) => {
    setDropTarget(targetId);
    // Announce drop target
    announceToScreenReader(`Drop target: ${targetId}`);
  };

  const handleDrop = (targetId: string) => {
    setDropTarget(null);
    announceToScreenReader(`Item dropped at ${targetId}`);
  };

  return {
    draggedItem,
    dropTarget,
    handleDragStart,
    handleDragEnd,
    handleDragOver,
    handleDrop
  };
};

Focus Management in Complex Scenarios

For multi-panel dashboards with nested drag zones:

// Focus management for nested dashboard layouts
const useNestedDashboardFocus = () => {
  const [activePanel, setActivePanel] = useState<string | null>(null);
  
  const handlePanelFocus = (panelId: string) => {
    setActivePanel(panelId);
    // Focus the first draggable item in this panel
    const firstItem = document.querySelector(
      `[data-panel="${panelId}"] [draggable="true"]`
    );
    if (firstItem) {
      (firstItem as HTMLElement).focus();
    }
  };

  const handleKeyboardNavigation = (e: KeyboardEvent) => {
    if (e.key === 'Escape') {
      // Cancel drag operation and restore focus
      setActivePanel(null);
      const activeElement = document.activeElement;
      if (activeElement instanceof HTMLElement) {
        activeElement.blur();
      }
    }
  };

  useEffect(() => {
    document.addEventListener('keydown', handleKeyboardNavigation);
    return () => {
      document.removeEventListener('keydown', handleKeyboardNavigation);
    };
  }, []);

  return { activePanel, handlePanelFocus };
};

Testing Strategy for Accessibility

• Automated testing: Use axe-core with Jest to validate ARIA compliance
• Manual keyboard testing: Verify all drag operations work via keyboard alone
• Screen reader testing: Validate NVDA, JAWS, and VoiceOver compatibility
• Color contrast testing: Ensure all drag states meet WCAG 2.1 AA requirements

Accessibility Testing Integration

// Accessibility testing setup for drag-and-drop dashboard
describe('Dashboard Accessibility', () => {
  beforeEach(() => {
    // Setup dashboard with proper ARIA attributes
    render(<Dashboard />);
  });

  it('should have proper ARIA roles and labels', () => {
    const items = screen.getAllByRole('article');
    expect(items).toHaveLength(3);
    
    // Verify all items have proper labels
    items.forEach(item => {
      expect(item).toHaveAttribute('aria-label');
    });
  });

  it('should support keyboard navigation', () => {
    const firstItem = screen.getByRole('article', { name: 'Widget 1' });
    
    // Simulate keyboard navigation
    fireEvent.keyDown(firstItem, { key: 'Enter' });
    
    // Verify drag state is announced
    expect(screen.getByText(/Dragging item/)).toBeInTheDocument();
  });

  it('should maintain focus within dashboard container', () => {
    const dashboard = screen.getByTestId('dashboard-container');
    
    // Verify focus is trapped
    expect(dashboard).toBeInTheDocument();
  });
});

10. Security Considerations

XSS Prevention Strategy

Content Sanitization: All user-generated content rendered in dashboard widgets must be sanitized using a robust HTML sanitizer like DOMPurify to prevent script injection. This includes:

• Widget titles and descriptions
• Dynamic content from external APIs
• User input in configuration forms

// Example sanitization approach
import DOMPurify from 'dompurify';

const sanitizeHTML = (html: string): string => {
  return DOMPurify.sanitize(html, {
    ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p', 'br'],
    ALLOWED_ATTR: ['class']
  });
};

Input Validation: All drag-and-drop operations must validate:

• Widget IDs to ensure they're within allowed ranges
• Position coordinates to prevent out-of-bounds manipulation
• Data types for all configuration parameters

CSRF Protection

Token Management: Implement CSRF token validation for all dashboard mutation operations:

• Include CSRF tokens in all POST/PUT/PATCH requests
• Generate tokens per session and invalidate on logout
• Use secure, HttpOnly cookies for token storage

// CSRF token handling in API client
const apiClient = axios.create({
  withCredentials: true,
  headers: {
    'X-CSRF-Token': getCSRFToken(),
    'Content-Type': 'application/json'
  }
});

Content Security Policy (CSP) Headers

Header Configuration: Implement strict CSP headers to prevent unauthorized script execution:

Content-Security-Policy: 
  default-src 'self'; 
  script-src 'self' 'unsafe-inline' 'unsafe-eval'; 
  style-src 'self' 'unsafe-inline';
  img-src 'self' data: https:;
  connect-src 'self' wss:;

Sensitive Data Handling in Frontend State

Data Exposure Prevention:

• Never store sensitive configuration data (API keys, secrets) in React state or localStorage
• Mask sensitive values in UI (e.g., show "•••••" instead of actual keys)
• Use secure storage mechanisms for sensitive tokens (HttpOnly cookies)

// Secure configuration handling
interface WidgetConfig {
  // Never store sensitive fields in frontend state
  id: string;
  title: string;
  type: string;
  // sensitiveFields: never stored in frontend state
}

Input Sanitization Approach

Comprehensive Validation:

• Validate widget position coordinates to prevent malicious coordinate ranges
• Sanitize all drag-and-drop event data before processing
• Implement rate limiting for dashboard reconfiguration operations
• Validate widget types against a whitelist to prevent arbitrary type injection

Security Boundary: The dashboard drag-and-drop feature operates within a controlled environment where:

• All widget data is validated server-side before storage
• Client-side validation serves as defense-in-depth, not security boundary
• Widget reordering operations are authenticated and authorized

Risk Mitigation

Known Risks:

1. Client-side manipulation: Users could potentially manipulate DOM or local storage to change widget behavior
2. Cross-site scripting: Malicious widgets could inject scripts if not properly sanitized
3. Session hijacking: CSRF tokens must be properly managed to prevent session manipulation

Mitigation Strategy:

• Server-side validation for all drag-and-drop operations
• Regular security audits of widget rendering logic
• Implementation of proper authentication and authorization checks for all dashboard mutations
• Regular updates to security libraries and CSP policies

11. Internationalization (i18n)

Translation Key Structure and Naming Convention

Translation keys will follow a hierarchical structure using dot notation for clear organization:

dashboard:
  widgets:
    title: "Widget Title"
    description: "Widget Description"
    drag_hint: "Drag me to reposition"
  empty_state:
    title: "No widgets added yet"
    description: "Add widgets to get started"
  actions:
    add_widget: "Add Widget"
    save_layout: "Save Layout"

Keys will use kebab-case for consistency and avoid special characters. Nested keys will be organized by feature areas to support modular translation loading.

RTL Support Considerations

RTL layout handling will be implemented through CSS classes and direction properties:

// In theme or global styles
[dir="rtl"] .dashboard-container {
  direction: rtl;
}

[dir="rtl"] .widget-drag-handle {
  left: auto;
  right: 12px;
}

Drag-and-drop positioning logic will be updated to respect RTL direction by:

• Flipping horizontal positioning calculations
• Adjusting drag preview alignment
• Reordering widget containers in RTL mode

Date, Number, Currency Formatting Strategy

All date and number formatting will use the Intl API with locale-aware formatters:

// i18n/utils.ts
export const formatDate = (date: Date, locale: string) => {
  return new Intl.DateTimeFormat(locale, {
    year: 'numeric',
    month: 'short',
    day: 'numeric'
  }).format(date);
};

export const formatNumber = (num: number, locale: string) => {
  return new Intl.NumberFormat(locale, {
    maximumFractionDigits: 2
  }).format(num);
};

Locale Detection and Switching Strategy

Automatic locale detection will use browser preferences:

// i18n/detectLocale.ts
export const detectLocale = (): string => {
  const browserLang = navigator.language || 'en-US';
  const supportedLocales = ['en-US', 'fr-FR', 'es-ES', 'ar-SA'];
  
  // Match to supported locales or default to en-US
  return supportedLocales.find(locale => 
    locale.startsWith(browserLang.split('-')[0])
  ) || 'en-US';
};

Locale switching will be handled via a context provider:

// i18n/LocaleContext.tsx
interface LocaleContextType {
  locale: string;
  setLocale: (locale: string) => void;
  t: (key: string, params?: Record<string, any>) => string;
}

const LocaleContext = createContext<LocaleContextType>({
  locale: 'en-US',
  setLocale: () => {},
  t: () => ''
});

The dashboard will support switching between:

• English (en-US)
• French (fr-FR)
• Spanish (es-ES)
• Arabic (ar-SA) - RTL support

Translations will be loaded dynamically via chunked bundles per locale to optimize initial load size.

12. Monitoring & Observability

Real User Monitoring (RUM) Metrics to Track

The drag-and-drop dashboard requires comprehensive RUM tracking to ensure optimal user experience and performance. Key metrics include:

• Drag Start to Drop Completion Time: Measure the end-to-end duration from when a user initiates a drag operation to when it's successfully dropped, targeting <200ms for 95% of operations
• Drop Position Accuracy: Track how often drag-and-drop operations land at intended positions, with target accuracy >95%
• Drag Rejection Rate: Monitor failed drop attempts due to invalid targets, with target rejection rate <5%
• Scroll Performance During Drag: Track if drag operations cause layout shifts or scrolling jank, with target LCP <2.5s
• User Session Duration: Monitor average session length to understand engagement patterns

Error Tracking Integration

Sentry integration will capture both frontend and backend errors:

• Drag-and-Drop Operation Failures: Capture when drag operations fail due to invalid targets, missing elements, or state inconsistencies
• State Management Errors: Track issues with drag state persistence and synchronization across components
• Performance Degradation: Log when drag operations exceed performance thresholds (e.g., >50ms to update drop zones)
• User Interaction Errors: Capture errors when users attempt drag operations on disabled or read-only elements

Custom Events and User Journey Tracking

Implement custom event tracking for key user flows:

// Event tracking interface
interface DragEvent {
  type: 'drag_start' | 'drag_move' | 'drag_end' | 'drop_success' | 'drop_failure';
  userId: string;
  dashboardId: string;
  sourceWidgetId: string;
  targetWidgetId?: string;
  timestamp: number;
  durationMs?: number;
  position?: { x: number; y: number };
}

// Example implementation in tracking service
class UserJourneyTracker {
  private events: DragEvent[] = [];
  
  track(event: DragEvent) {
    this.events.push(event);
    // Send to analytics backend or RUM service
    this.sendToRumService(event);
  }
}

Performance Monitoring and Regression Detection

Performance monitoring includes:

• Drag Operation Latency: Track average drag operation response time, with target <100ms for 95% of operations
• Memory Usage: Monitor DOM node count and memory consumption during drag operations, with target <50MB increase
• FPS During Drag: Ensure >50 FPS during active drag operations, with target >60 FPS for smooth experience
• Bundle Size Impact: Monitor drag-and-drop feature bundle size, with target <5KB increase from core dependencies

Integration with Observability Platforms

• Datadog APM: Integrate with Datadog for full-stack performance monitoring, including backend drag operation sync times
• New Relic: Use New Relic for real-time dashboard performance alerts and user behavior analytics
• LogRhythm: Implement structured logging for drag operation audit trails in production environments

Alerting Strategy

Critical alerts will be configured for:

• Drag operation failure rate >2% over 5-minute window
• Average drag duration >200ms for 95th percentile over 15-minute window
• Memory usage spikes >20% during drag operations
• User session abandonment rate >15% for dashboard with drag functionality

Data Retention and Privacy

• Data Retention: 90-day retention for performance metrics, 30-day retention for user journey data
• Privacy Compliance: All tracking data will be anonymized and comply with GDPR/CCPA requirements
• User Opt-Out: Provide user opt-out mechanism for performance tracking (via feature flags or settings)

Dashboard Performance Metrics

Dashboard-specific metrics include:

• Widget Reordering Success Rate: Track successful drag-and-drop operations for widget reordering, with target >98%
• Drop Zone Hit Rate: Monitor how often drag operations land on valid drop zones, with target >95%
• Concurrent Drag Operations: Track simultaneous drag operations per user session, with target <5 concurrent operations
• Drop Zone Validation Time: Measure time to validate drop zones during drag operations, with target <50ms validation time

13. File & Folder Structure

Proposed Directory Structure

/src
  /components
    /dashboard
      Dashboard.tsx
      Widget.tsx
      WidgetPlaceholder.tsx
      DragHandle.tsx
      WidgetGrid.tsx
    /common
      Button.tsx
      Icon.tsx
      Modal.tsx
  /features
    /dashboard
      index.ts
      types.ts
      hooks.ts
      utils.ts
      constants.ts
  /hooks
    useDashboardDragAndDrop.ts
    useWidgetLayout.ts
  /types
    dashboard.ts
  /utils
    arrayUtils.ts
    domUtils.ts
  /services
    dashboardService.ts

Module Boundaries and Import Rules

• Feature isolation: Dashboard feature components live in /features/dashboard to avoid cross-feature imports
• Shared components: Common UI elements like Button and Icon are in /components/common with barrel exports
• Type safety: All feature-specific types live in their respective feature folders (e.g., dashboard/types.ts)
• Reusability: Hooks and utilities that can be reused across features are in /hooks and /utils

Shared vs Feature-Specific Code

Shared code:

• Common UI components (Button, Icon)
• Utility functions (array manipulation, DOM helpers)
• Global types and constants

Feature-specific code:

• Dashboard layout and drag-and-drop logic
• Widget rendering and configuration
• API service layer for dashboard operations

This structure enables clear module boundaries, prevents circular dependencies, and supports scalable growth of the dashboard feature while maintaining shared component reuse.

14. Dependencies & Third-Party Libraries

Key Libraries Selected with Justification

1. react-beautiful-dnd

• Justification: Industry-standard drag-and-drop solution with excellent browser support, accessibility features, and comprehensive documentation. Provides stable, well-tested abstractions for drag-and-drop interactions.
• Bundle size: ~25KB (minified + gzipped)
• Features: HTML5 drag-and-drop API integration, keyboard accessibility, touch support, smooth animations

2. react-dnd

• Alternative consideration: More flexible and feature-rich than react-beautiful-dnd, but with higher complexity and steeper learning curve.
• Why not selected: Overkill for dashboard use case; react-beautiful-dnd provides sufficient functionality with cleaner API

3. framer-motion

• Justification: Excellent for implementing smooth animations and transitions in drag-and-drop interactions. Provides performant, declarative animation primitives.
• Bundle size: ~15KB (minified + gzipped)
• Features: Physics-based animations, gesture support, layout animations

4. react-icons

• Justification: Consistent iconography across dashboard components with minimal bundle impact.
• Bundle size: ~5KB (minified + gzipped)
• Features: Comprehensive icon set, tree-shaking support

5. date-fns

• Justification: Modern, modular date formatting library with excellent TypeScript support and zero dependencies.
• Bundle size: ~2KB (minified + gzipped)
• Features: Strong TypeScript typing, immutable operations, locale support

Alternatives Considered and Rejected

1. react-sortable-hoc

• Rejected because: Outdated maintenance, limited accessibility support, less active community. React-beautiful-dnd has better long-term viability.

2. @dnd-kit

• Rejected because: While powerful, it introduces more complexity than needed for dashboard drag-and-drop. react-beautiful-dnd offers simpler implementation with similar functionality.

3. react-grid-layout

• Rejected because: Specifically designed for grid-based layouts, not general dashboard drag-and-drop. Would require significant adaptation for flexible widget placement.

Licensing and Bundle Size Impact Assessment

License Compliance: All selected libraries use MIT or BSD-3-Clause licenses, suitable for commercial applications. License scanning is performed during CI pipeline.

Bundle Size Budget Allocation:

• react-beautiful-dnd: 25KB (12% of total dashboard bundle)
• framer-motion: 15KB (7.5% of total dashboard bundle)
• react-icons: 5KB (2.5% of total dashboard bundle)
• date-fns: 2KB (1% of total dashboard bundle)

Tree-shaking Strategy: All libraries support tree-shaking to minimize final bundle size. Only required components are imported.

Performance Considerations

Bundle Size Optimization:

• All libraries use ES modules for better tree-shaking
• react-beautiful-dnd's drag handle and drop zone components are selectively imported to reduce bundle size
• framer-motion animations are optimized using motion variants rather than inline styles

Code Splitting:

• react-beautiful-dnd is imported as a dynamic import to reduce initial bundle size
• react-icons are selectively imported using specific icon components rather than entire icon sets

Integration Strategy

TypeScript Support: All libraries have comprehensive TypeScript definitions with strict type checking support.

Testing Compatibility:

• react-beautiful-dnd has extensive test coverage and is compatible with Jest
• framer-motion works seamlessly with React Testing Library
• react-icons are fully compatible with TypeScript and testing frameworks

Build Tool Integration:

• All libraries integrate smoothly with Webpack, Vite, and Next.js
• No custom webpack configurations required for basic usage

15. Open Questions, Risks & Trade-offs

Decisions that need product/engineering alignment

• Drag threshold and sensitivity configuration - Should users be able to customize drag sensitivity or minimum drag distance before activation? This requires product alignment on whether this is a feature or configuration.
• Drop zone validation rules - Should drop zones support flexible validation (e.g., "can accept any widget" vs. "only accepts widgets of type X") or should this be hardcoded in the component?
• Cross-dashboard drag support - Should widgets be draggable between different dashboard instances? This impacts state management complexity and requires backend API design for cross-dashboard moves.

Known trade-offs made in this design

• Simplified DOM structure - Using a flat component tree instead of nested containers to reduce complexity, but this may limit future extensibility for hierarchical dashboard structures.
• Limited touch device support - Prioritized mouse-based drag operations over comprehensive touch handling, which may impact mobile experience and require additional work for full touch support.
• Single widget type - Design assumes uniform widget types to simplify state management, but this limits flexibility for mixed-type dashboards.

Risks and mitigations

• Performance degradation with large widget sets - Risk of slow drag operations with >50 widgets. Mitigation: Implement virtualization for widget lists and optimize DOM rendering.
• State synchronization issues - Risk of inconsistent state between client and server during drag operations. Mitigation: Use optimistic updates with proper rollback handling and server-side validation.
• Accessibility compliance gaps - Risk of incomplete keyboard navigation support. Mitigation: Comprehensive accessibility testing and progressive enhancement strategy.

Technical debt acknowledged

• Limited extensibility - Current design assumes fixed widget types, making future widget type additions more complex and requiring refactoring of the drag-and-drop logic.
• No undo/redo support - Missing history tracking for drag operations, which will require additional state management complexity to implement properly.
• Hardcoded styling - CSS classes are not abstracted into a design system, making them harder to customize and maintain in large-scale applications.
• No animation optimization - CSS transitions are not optimized for performance, which could cause jank in complex drag scenarios.