MyClub/ADMIN_NAV_SCROLL_CENTERING.md

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

// 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:

// 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:

{
  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:

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.