feature/IO-3497-Ant-Design-v5-to-v6 - Checkpoint (react-grid-layout future migration guide to new api)
This commit is contained in:
Dave
251
_reference/REACT_GRID_LAYOUT_MIGRATION.md
Normal file
251
_reference/REACT_GRID_LAYOUT_MIGRATION.md
Normal file
@@ -0,0 +1,251 @@
|
|||||||
|
# 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
|
||||||
Reference in New Issue
Block a user