hot fix #1

2026-06-04 02:32:57 +00:00 · 2026-01-26 08:13:18 +01:00
parent aa036b6550
commit dfc079288f
505 changed files with 95755 additions and 5712 deletions
@@ -0,0 +1,152 @@
+# Admin Navigation Auto-Centering Implementation
+
+## Overview
+The admin sidebar now automatically centers the current page navigation item in view, providing clear visual feedback about the user's current location in the admin panel.
+
+## How It Works
+
+### 1. Hook Implementation
+- **File**: `frontend/src/hooks/useAdminNavScrollRetention.ts`
+- **Purpose**: Automatically centers the current page's nav item in the sidebar viewport
+- **Trigger**: On route changes and component mount
+
+### 2. Centering Logic
+```typescript
+// Calculate scroll position to center the item
+const targetScrollTop = itemTopRelativeToContainer - (containerHeight / 2) + (itemHeight / 2);
+
+// Ensure we don't scroll beyond bounds
+const finalScrollTop = Math.max(0, Math.min(targetScrollTop, maxScrollTop));
+
+// Smooth scroll to position
+container.scrollTo({
+  top: finalScrollTop,
+  behavior: 'smooth'
+});
+```
+
+### 3. Navigation Matching
+- **Exact match**: `/admin/sponzori` matches `href="/admin/sponzori"`
+- **Partial match**: `/admin/scoreboard/remote` matches `href="/admin/scoreboard"`
+- **Priority**: Exact matches take precedence over partial matches
+
+## Features
+
+### ✅ Automatic Centering
+- Centers the current page item in the sidebar viewport
+- Uses smooth scrolling for polished user experience
+- Handles edge cases (top/bottom boundaries)
+
+### ✅ Smart Matching
+- Exact path matching for most pages
+- Partial matching for nested routes (e.g., scoreboard remote)
+- Fallback handling for missing nav items
+
+### ✅ Performance Optimized
+- Debounced scrolling to prevent conflicts
+- Proper cleanup of event listeners
+- Minimal DOM queries
+
+### ✅ Debug Support
+- Development mode logging
+- Detailed calculation output
+- Test script included
+
+## Testing
+
+### Manual Testing
+1. Navigate to different admin pages
+2. Observe sidebar auto-centering the current page item
+3. Check smooth scrolling behavior
+4. Test edge cases (first/last items)
+
+### Automated Testing
+Run the test script in browser console:
+```javascript
+// Copy and paste contents of test-scroll-retention.js
+```
+
+### Expected Behavior
+- `/admin` → Centers "Nástěnka" item
+- `/admin/sponzori` → Centers "Sponzoři" item  
+- `/admin/analytika` → Centers "Analytika" item
+- `/admin/scoreboard/remote` → Centers "Scoreboard Remote" item
+
+## File Changes
+
+### Modified Files
+1. **`frontend/src/hooks/useAdminNavScrollRetention.ts`**
+   - Complete rewrite for auto-centering functionality
+   - Removed scroll position storage/restoration
+   - Added nav item detection and centering logic
+
+2. **`frontend/src/components/admin/AdminSidebar.tsx`**
+   - Updated to use new hook API
+   - Removed manual scroll save/restore logic
+   - Simplified NavItem interface
+
+3. **`frontend/src/i18n/index.ts`**
+   - Fixed duplicate `tables` property causing build errors
+
+### Added Files
+1. **`test-scroll-retention.js`**
+   - Comprehensive test script for validation
+   - Can be run in browser console
+   - Tests multiple scenarios and edge cases
+
+## Configuration Options
+
+The hook accepts these options:
+```typescript
+{
+  scrollContainerSelector?: string; // Default: '[data-sidebar="true"]'
+  navItemSelector?: string;         // Default: 'a[href*="/admin/"]'
+  enableDebug?: boolean;           // Default: false
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Auto-centering not working**
+   - Check if sidebar has `data-sidebar="true"` attribute
+   - Verify nav items have correct `href` attributes
+   - Check browser console for debug messages
+
+2. **Scrolling to wrong position**
+   - Ensure sidebar has proper height/scroll dimensions
+   - Check for CSS conflicts affecting positioning
+   - Verify container boundaries calculation
+
+3. **Performance issues**
+   - Check for excessive re-renders
+   - Verify event listener cleanup
+   - Monitor for memory leaks
+
+### Debug Mode
+Enable debug logging by setting:
+```typescript
+useAdminNavScrollRetention({
+  enableDebug: true
+});
+```
+
+Or use development environment (automatically enables debug).
+
+## Future Enhancements
+
+1. **Animation customization**: Allow custom scroll behavior
+2. **Position memory**: Remember user's preferred scroll position
+3. **Keyboard navigation**: Support arrow key navigation with centering
+4. **Mobile optimization**: Different behavior for mobile viewports
+5. **Accessibility**: ARIA labels and screen reader support
+
+## Browser Compatibility
+
+- ✅ Chrome 61+
+- ✅ Firefox 36+
+- ✅ Safari 14+
+- ✅ Edge 79+
+
+Uses standard `scrollTo()` API with `behavior: 'smooth'` option.