From ebe51fed2cf813b1c3535517484d3da48ae943da Mon Sep 17 00:00:00 2001 From: Dave Date: Tue, 13 Jan 2026 13:03:13 -0500 Subject: [PATCH] feature/IO-3497-Ant-Design-v5-to-v6 - Checkpoint (react-grid-layout future migration guide to new api) --- _reference/REACT_GRID_LAYOUT_MIGRATION.md | 251 ++++++++++++++++++++++ 1 file changed, 251 insertions(+) create mode 100644 _reference/REACT_GRID_LAYOUT_MIGRATION.md diff --git a/_reference/REACT_GRID_LAYOUT_MIGRATION.md b/_reference/REACT_GRID_LAYOUT_MIGRATION.md new file mode 100644 index 000000000..2c1a66c37 --- /dev/null +++ b/_reference/REACT_GRID_LAYOUT_MIGRATION.md @@ -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 ( + + {children} + +); +``` + +**After:** +```javascript +import ReactGridLayout, { useContainerWidth, verticalCompactor } from 'react-grid-layout'; + +function DashboardGridComponent({ currentUser }) { + const { width, containerRef, mounted } = useContainerWidth(); + + return ( +
+ {mounted && ( + + {children} + + )} +
+ ); +} +``` + +#### 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 ( +
+ {mounted && ( + + {children} + + )} +
+ ); +} +``` + +#### Step 3: Update Child Components + +The `data-grid` attribute still works, but explicitly managing layout is preferred: + +**Before:** +```javascript +
+ {content} +
+``` + +**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 +
+ {content} +
+``` + +#### 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