Filament Collapsible Subnav Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require emuniq/filament-collapsible-subnav
   

   The package auto-registers to all Filament panels with zero configuration.

2. First Use Case: Navigate to any resource page (e.g., /admin/posts) with sub-navigation (e.g., ->subNavigationPosition(SubNavigationPosition::Start)). A collapsible toggle button will appear in the sub-navigation sidebar, allowing users to expand/collapse sections.

3. Where to Look First:

   • Resource Pages: Check pages with subNavigationPosition() defined (e.g., PostResource, PageResource).
   • Panel Configuration: Verify ->spa() or ->navigationPosition() settings don’t interfere (though the plugin handles both seamlessly).

Implementation Patterns

Usage Patterns

1. Auto-Registration:

   • Works out-of-the-box for all panels. No manual setup required unless overriding defaults.
   • Example: A PostResource with sub-navigation will automatically gain collapsible functionality.

2. Manual Registration (Optional): For granular control, register the plugin explicitly in a panel:

   use Emuniq\FilamentCollapsibleSubnav\CollapsibleSubnavPlugin;
   
   public function panel(Panel $panel): Panel {
       return $panel
           ->plugin(CollapsibleSubnavPlugin::make());
   }
   

3. Integration with Existing Workflows:

   • SPA Mode: The plugin listens to livewire:navigated to re-sync collapsed state after Livewire SPA navigation.
   • Dark Mode: Tooltips and UI automatically adapt to Filament’s dark mode (no additional config).
   • Responsive Design: Sub-navigation collapses on mobile (<768px) by default.

4. Customization:

   • CSS Overrides: Extend the plugin’s styles via your Filament theme (e.g., override .collapsible-subnav-toggle).
   • Cookie Persistence: State is saved to subnav_collapsed cookie. Override via:

     CollapsibleSubnavPlugin::make()->cookieName('custom_subnav_state');
     

5. Theme Integration (Optional): For performance, bundle CSS with your theme:

   php artisan collapsible-subnav:install
   npm run build
   

Workflows

1. Admin Panel Upgrade:

   • Upgrade Filament to v5? The plugin supports ^3.0|^4.0|^5.0 with no breaking changes.
   • Example:

     composer require filament/filament:"^5.0"
     composer require emuniq/filament-collapsible-subnav
     

2. A/B Testing:

   • Enable the plugin on a subset of resources (e.g., via manual registration) to measure UX impact before full rollout.

3. Accessibility Audits:

   • Verify aria-label and dark-mode tooltips pass WCAG checks. The plugin handles this automatically, but test with screen readers.

Integration Tips

• Livewire SPA Apps: Ensure livewire:navigated events are not blocked by your SPA setup (e.g., Alpine.js or custom event listeners).
• Custom Navigation: If using non-standard sub-navigation (e.g., Blade templates), manually trigger the plugin’s JS:

  document.querySelector('.collapsible-subnav-toggle').addEventListener('click', () => {
      // Custom logic
  });
  

• Filament v5 Migration: The plugin handles v5’s renamed classes (e.g., .fi-sidebar-item-btn) internally. Test on a staging panel post-upgrade.

Gotchas and Tips

Pitfalls

1. Cloudflare Rocket Loader:

   • Issue: May strip critical inline scripts, causing flashes on reload.
   • Fix: The plugin marks its script with data-cfasync="false". If issues persist, whitelist the script in Cloudflare or disable Rocket Loader for Filament pages.

2. SPA Mode Desync (Pre-v1.6.0):

   • Issue: Collapsed state might not persist across Livewire SPA navigation.
   • Fix: Updated in v1.6.0 with livewire:navigated listener. Ensure your Filament version is ≥1.6.0.

3. Tooltips in Filament v4:

   • Issue: Tooltips may not appear due to Tippy not being globally available.
   • Fix: The plugin now uses CSS-only ::after tooltips, ensuring compatibility across v3/v4/v5.

4. Mobile Responsiveness:

   • Issue: Sub-navigation may not collapse on mobile if custom CSS overrides screen width checks.
   • Fix: Ensure no global CSS targets .collapsible-subnav with display: block !important on small screens.

5. Cookie Conflicts:

   • Issue: Custom subnav_collapsed cookie names might conflict with other plugins.
   • Fix: Use a unique prefix (e.g., filament_subnav_collapsed).

Debugging

1. Toggle Not Appearing:

   • Check: Verify the page has sub-navigation (e.g., ->subNavigationPosition()).
   • Debug: Inspect the DOM for .collapsible-subnav-toggle. If missing, the plugin failed to auto-register. Manually register it in the panel.

2. State Not Persisting:

   • Check: Cookies enabled? Inspect subnav_collapsed in browser dev tools.
   • Debug: Clear cookies and test. If state resets, the plugin’s JS may be blocked (e.g., by CSP).

3. CSS Overrides Broken:

   • Check: Your theme’s CSS might override plugin styles. Use !important sparingly; target specific classes like .collapsible-subnav-toggle.

4. SPA Mode Issues:

   • Check: Listen for livewire:navigated events in browser console. If missing, your SPA setup may suppress them.
   • Debug: Add a global event listener:

     document.addEventListener('livewire:navigated', () => {
         console.log('Livewire navigated - plugin should re-sync');
     });
     

Tips

1. Performance Optimization:

   • Use the collapsible-subnav:install Artisan command to bundle CSS with your theme, reducing HTTP requests.

2. Dark Mode Styling:

   • Customize dark-mode tooltips by overriding:

     .dark .collapsible-subnav-tooltip {
         background: #333;
         color: #fff;
     }
     

3. Accessibility:

   • Screen readers: The plugin adds aria-label to collapsed items. Test with NVDA/VoiceOver to confirm.

4. Filament v5 Migration:

   • The plugin handles v5’s structural changes automatically. Test on a staging panel to catch edge cases (e.g., new sidebar classes).

5. Extending Functionality:

   • Add custom logic to the toggle click event:

     document.querySelector('.collapsible-subnav-toggle').addEventListener('click', (e) => {
         // Example: Log analytics
         console.log('Subnav toggled', e.target.dataset.state);
     });
     

6. Localization:

   • Tooltips use aria-label. Localize by overriding the attribute:

     // In your resource/page class
     public static function getCollapsedTooltip(): string {
         return __('filament-collapsible-subnav::toggle.collapse');
     }