# React Grid Layout Migration Guide

## Current Status: Legacy API (v2.2.2)

### What Changed
- **Package Version**: 1.3.4 → 2.2.2
- **API Strategy**: Using legacy compatibility layer

### Migration Completed ✅

#### Changes Made:
```javascript
// Before (v1.3.4):
import { Responsive, WidthProvider } from "react-grid-layout";

// After (v2.2.2 with legacy API):
import { Responsive, WidthProvider } from "react-grid-layout/legacy";
```

#### Files Updated:
- `src/components/dashboard-grid/dashboard-grid.component.jsx`

#### Why Legacy API?
The v2.x release introduces a completely new hooks-based API with breaking changes. The legacy API provides 100% backward compatibility, allowing us to:
- ✅ Get bug fixes and security updates
- ✅ Maintain existing functionality without code rewrites
- ✅ Plan migration to new API incrementally

---

## Future: Migration to New v2 API

When ready to fully migrate to the modern v2 API, follow this guide:

### Breaking Changes in v2

1. **Width Provider Removed**
   - Old: `WidthProvider(Responsive)`
   - New: Use `useContainerWidth` hook

2. **Props Restructured**
   - Old: Flat props structure
   - New: Grouped configs (`gridConfig`, `dragConfig`, `resizeConfig`)

3. **Layout Prop Required**
   - Old: Could use `data-grid` attribute
   - New: Must provide `layout` prop explicitly

4. **Compaction Changes**
   - Old: `verticalCompact` prop
   - New: `compactor` prop with pluggable algorithms

### Migration Steps

#### Step 1: Replace WidthProvider with useContainerWidth hook

**Before:**
```javascript
const ResponsiveReactGridLayout = WidthProvider(Responsive);

return (
  <ResponsiveReactGridLayout
    className="layout"
    breakpoints={GRID_BREAKPOINTS}
    cols={GRID_COLS}
    layouts={state.layouts}
    onLayoutChange={handleLayoutChange}
  >
    {children}
  </ResponsiveReactGridLayout>
);
```

**After:**
```javascript
import ReactGridLayout, { useContainerWidth, verticalCompactor } from 'react-grid-layout';

function DashboardGridComponent({ currentUser }) {
  const { width, containerRef, mounted } = useContainerWidth();
  
  return (
    <div ref={containerRef}>
      {mounted && (
        <ReactGridLayout
          width={width}
          layout={state.layout}
          gridConfig={{
            cols: 12,
            rowHeight: 30,
            margin: [10, 10]
          }}
          dragConfig={{
            enabled: true,
            handle: '.drag-handle' // optional
          }}
          resizeConfig={{
            enabled: true
          }}
          compactor={verticalCompactor}
          onLayoutChange={handleLayoutChange}
        >
          {children}
        </ReactGridLayout>
      )}
    </div>
  );
}
```

#### Step 2: Update Responsive Layouts

For responsive behavior, manage breakpoints manually:

```javascript
function DashboardGridComponent() {
  const { width, containerRef, mounted } = useContainerWidth();
  const [currentBreakpoint, setCurrentBreakpoint] = useState('lg');
  
  useEffect(() => {
    if (width > 1200) setCurrentBreakpoint('lg');
    else if (width > 996) setCurrentBreakpoint('md');
    else if (width > 768) setCurrentBreakpoint('sm');
    else if (width > 480) setCurrentBreakpoint('xs');
    else setCurrentBreakpoint('xxs');
  }, [width]);

  const currentLayout = state.layouts[currentBreakpoint] || state.layout;
  const currentCols = GRID_COLS[currentBreakpoint];

  return (
    <div ref={containerRef}>
      {mounted && (
        <ReactGridLayout
          width={width}
          layout={currentLayout}
          gridConfig={{
            cols: currentCols,
            rowHeight: 30
          }}
          // ... other props
        >
          {children}
        </ReactGridLayout>
      )}
    </div>
  );
}
```

#### Step 3: Update Child Components

The `data-grid` attribute still works, but explicitly managing layout is preferred:

**Before:**
```javascript
<div
  key={item.i}
  data-grid={{
    ...item,
    minH,
    minW
  }}
>
  {content}
</div>
```

**After (Preferred):**
```javascript
// Manage layout in parent state
const layout = state.items.map(item => ({
  i: item.i,
  x: item.x,
  y: item.y,
  w: item.w,
  h: item.h,
  minW: componentList[item.i]?.minW || 1,
  minH: componentList[item.i]?.minH || 1
}));

// Children just need keys
<div key={item.i}>
  {content}
</div>
```

#### Step 4: Update Styles (if needed)

The CSS classes remain mostly the same, but check the new documentation for any changes.

### Benefits of New API

- 🚀 **Better Performance**: Optimized rendering with hooks
- 📦 **TypeScript Support**: Full type definitions included
- 🎯 **Better API**: More intuitive props organization
- 🔧 **Extensibility**: Pluggable compactors and strategies
- 📱 **Modern React**: Uses hooks pattern

### Testing Checklist

When migrating to new API:

- [ ] Grid items render correctly
- [ ] Drag functionality works
- [ ] Resize functionality works  
- [ ] Responsive breakpoints work
- [ ] Layout persistence works
- [ ] Add/remove components works
- [ ] Min/max constraints respected
- [ ] Performance is acceptable
- [ ] No console errors or warnings

### Resources

- [React Grid Layout v2 Documentation](https://github.com/react-grid-layout/react-grid-layout)
- [Migration Guide](https://www.npmjs.com/package/react-grid-layout)
- [Examples](https://github.com/react-grid-layout/react-grid-layout/tree/master/examples)

---

## Current Implementation Notes

### Component Structure
- **File**: `src/components/dashboard-grid/dashboard-grid.component.jsx`
- **Styles**: `src/components/dashboard-grid/dashboard-grid.styles.scss`
- **Pattern**: Responsive grid with dynamic component loading

### Key Features Used
- ✅ Responsive layouts with breakpoints
- ✅ Drag and drop
- ✅ Resize handles
- ✅ Layout persistence to database
- ✅ Dynamic component add/remove
- ✅ Min/max size constraints

### Configuration
```javascript
const GRID_BREAKPOINTS = { lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 };
const GRID_COLS = { lg: 12, md: 10, sm: 6, xs: 4, xxs: 2 };
```

### Performance Considerations
- Layout changes debounced via database updates
- Memoized dashboard queries to prevent re-fetches
- Memoized menu items and layout keys

---

**Last Updated**: 2026-01-13  
**Current Version**: react-grid-layout@2.2.2 (legacy API)  
**Target Version**: react-grid-layout@2.2.2 (new API) - Future migration