|
| 1 | +# Virtualized Asset Grid Components |
| 2 | + |
| 3 | +This document explains how to use the new React Window-based virtualized asset grid components for better performance with large datasets. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The virtualized asset grid components provide significant performance improvements when displaying large numbers of assets by only rendering the items that are currently visible in the viewport. This is especially useful for photo galleries with thousands of images. |
| 8 | + |
| 9 | +## Components |
| 10 | + |
| 11 | +### 1. VirtualizedAssetGrid |
| 12 | + |
| 13 | +A basic virtualized grid with fixed dimensions. |
| 14 | + |
| 15 | +```tsx |
| 16 | +import VirtualizedAssetGrid from '@/components/shared/VirtualizedAssetGrid'; |
| 17 | + |
| 18 | +<VirtualizedAssetGrid |
| 19 | + assets={assets} |
| 20 | + selectable={true} |
| 21 | + onSelectionChange={handleSelectionChange} |
| 22 | + columnCount={5} |
| 23 | + itemSize={200} |
| 24 | + height={600} |
| 25 | +/> |
| 26 | +``` |
| 27 | + |
| 28 | +**Props:** |
| 29 | +- `assets`: Array of IAsset objects |
| 30 | +- `selectable`: Whether assets can be selected (default: false) |
| 31 | +- `onSelectionChange`: Callback when selection changes |
| 32 | +- `columnCount`: Number of columns (default: 5) |
| 33 | +- `itemSize`: Size of each item in pixels (default: 200) |
| 34 | +- `height`: Height of the grid container (default: 600) |
| 35 | + |
| 36 | +### 2. ResponsiveVirtualizedAssetGrid |
| 37 | + |
| 38 | +A responsive virtualized grid that automatically adjusts to container size. |
| 39 | + |
| 40 | +```tsx |
| 41 | +import ResponsiveVirtualizedAssetGrid from '@/components/shared/ResponsiveVirtualizedAssetGrid'; |
| 42 | + |
| 43 | +<ResponsiveVirtualizedAssetGrid |
| 44 | + assets={assets} |
| 45 | + selectable={true} |
| 46 | + onSelectionChange={handleSelectionChange} |
| 47 | + targetItemSize={200} |
| 48 | + gap={8} |
| 49 | + minColumns={2} |
| 50 | + maxColumns={8} |
| 51 | + className="w-full h-full" |
| 52 | +/> |
| 53 | +``` |
| 54 | + |
| 55 | +**Props:** |
| 56 | +- `assets`: Array of IAsset objects |
| 57 | +- `selectable`: Whether assets can be selected (default: false) |
| 58 | +- `onSelectionChange`: Callback when selection changes |
| 59 | +- `targetItemSize`: Target size for each item (default: 200) |
| 60 | +- `gap`: Gap between items in pixels (default: 8) |
| 61 | +- `minColumns`: Minimum number of columns (default: 2) |
| 62 | +- `maxColumns`: Maximum number of columns (default: 8) |
| 63 | +- `className`: Additional CSS classes |
| 64 | + |
| 65 | +## Features |
| 66 | + |
| 67 | +### Selection |
| 68 | +Both components support asset selection with the following features: |
| 69 | +- Click to select/deselect individual assets |
| 70 | +- Shift+click for range selection |
| 71 | +- ESC key to clear all selections |
| 72 | +- Visual indicators for selected items |
| 73 | + |
| 74 | +### Lightbox Integration |
| 75 | +Both components integrate with the existing lightbox for full-screen viewing: |
| 76 | +- Click on an asset to open in lightbox |
| 77 | +- Video support with duration display |
| 78 | +- Download functionality |
| 79 | + |
| 80 | +### Performance Optimizations |
| 81 | +- Only renders visible items |
| 82 | +- Lazy loading of images |
| 83 | +- Efficient memory usage |
| 84 | +- Smooth scrolling performance |
| 85 | + |
| 86 | +## Migration from AssetGrid |
| 87 | + |
| 88 | +To migrate from the existing `AssetGrid` component: |
| 89 | + |
| 90 | +### Before: |
| 91 | +```tsx |
| 92 | +import AssetGrid from '@/components/shared/AssetGrid'; |
| 93 | + |
| 94 | +<AssetGrid |
| 95 | + assets={assets} |
| 96 | + selectable={true} |
| 97 | + onSelectionChange={handleSelectionChange} |
| 98 | +/> |
| 99 | +``` |
| 100 | + |
| 101 | +### After: |
| 102 | +```tsx |
| 103 | +import ResponsiveVirtualizedAssetGrid from '@/components/shared/ResponsiveVirtualizedAssetGrid'; |
| 104 | + |
| 105 | +<div style={{ height: '600px', width: '100%' }}> |
| 106 | + <ResponsiveVirtualizedAssetGrid |
| 107 | + assets={assets} |
| 108 | + selectable={true} |
| 109 | + onSelectionChange={handleSelectionChange} |
| 110 | + targetItemSize={200} |
| 111 | + gap={8} |
| 112 | + minColumns={2} |
| 113 | + maxColumns={8} |
| 114 | + /> |
| 115 | +</div> |
| 116 | +``` |
| 117 | + |
| 118 | +**Important:** The virtualized components require a container with a defined height. Make sure to wrap them in a div with appropriate height styling. |
| 119 | + |
| 120 | +## Custom Hook: useGridDimensions |
| 121 | + |
| 122 | +The `useGridDimensions` hook can be used to calculate optimal grid dimensions: |
| 123 | + |
| 124 | +```tsx |
| 125 | +import { useGridDimensions } from '@/hooks'; |
| 126 | + |
| 127 | +const gridDimensions = useGridDimensions({ |
| 128 | + containerWidth: 800, |
| 129 | + containerHeight: 600, |
| 130 | + itemSize: 200, |
| 131 | + gap: 8, |
| 132 | + minColumns: 2, |
| 133 | + maxColumns: 8 |
| 134 | +}); |
| 135 | +``` |
| 136 | + |
| 137 | +## Example Usage |
| 138 | + |
| 139 | +See `src/components/shared/AssetGridExample.tsx` for a complete example showing different configurations of the virtualized grid components. |
| 140 | + |
| 141 | +## Performance Considerations |
| 142 | + |
| 143 | +- Use `ResponsiveVirtualizedAssetGrid` for most use cases as it automatically adapts to container size |
| 144 | +- Set appropriate `targetItemSize` based on your design requirements |
| 145 | +- Consider using smaller `gap` values for dense layouts |
| 146 | +- The components work best with containers that have a defined height |
| 147 | + |
| 148 | +## Browser Support |
| 149 | + |
| 150 | +The components use modern browser APIs: |
| 151 | +- ResizeObserver (for responsive behavior) |
| 152 | +- IntersectionObserver (for lazy loading) |
| 153 | +- CSS Grid and Flexbox |
| 154 | + |
| 155 | +For older browsers, consider using polyfills or the basic `VirtualizedAssetGrid` with fixed dimensions. |
0 commit comments