Filament Collapsible Subnav Laravel Package

Product Decisions This Supports

• Enhanced UX for complex admin panels: Justifies investment in Filament v5 upgrades by providing a seamless collapsible sub-navigation experience, reducing cognitive load for users managing deep resource hierarchies (e.g., SaaS platforms with multi-level permissions or content moderation tools).
• Accelerated Filament v5 migration: Lowers risk of adopting Filament v5 by ensuring critical UI components (like sub-navigation) remain functional without rewrite effort. Aligns with roadmaps for teams upgrading from v3/v4 to v5.
• Accessibility compliance: Addresses WCAG gaps (e.g., aria-label, dark-mode tooltips) to meet regulatory requirements (e.g., Section 508, GDPR) or internal audits, particularly for public-facing admin panels (e.g., government portals, healthcare systems).
• SPA/real-time optimization: Enables smoother navigation in Livewire-heavy applications (e.g., collaborative dashboards, live analytics), directly impacting user retention metrics.
• Vendor-backed reliability: Leverages Emuniq’s maintenance (GitHub Sponsors, explicit support) to reduce technical debt for long-term projects, justifying inclusion in vendor evaluation criteria.
• A/B testing infrastructure: Zero-configuration deployment allows safe experimentation with collapsible navigation on specific resource pages (e.g., "Orders" vs. "Customers") to measure engagement before full rollout.

When to Consider This Package

• Adopt when:

  • Your Filament version roadmap includes v5 (or you’re already on v5) and you need sub-navigation improvements without rewrites.
  • Sub-navigation clutter is a top UX pain point (e.g., >5 sub-items per resource page), identified via analytics (e.g., high bounce rates on complex pages).
  • You require cross-version compatibility (v3/v4/v5) to support legacy and modern stacks simultaneously (e.g., monorepos with mixed Filament versions).
  • Accessibility audits flag missing aria-label or dark-mode issues in sub-navigation, and you lack bandwidth to build custom solutions.
  • Your team uses Livewire SPA mode (->spa()) and experiences navigation state desync (e.g., collapsed states resetting on route changes).
  • You need a low-risk UX iteration (e.g., piloting collapsible nav on a single resource page before full deployment).
  • Your design system allows third-party CSS classes (e.g., .fi-sidebar-item-btn) and you prioritize maintainability over custom builds.

• Look elsewhere if:

  • You’re not using Filament (this package is Filament-specific).
  • Your navigation structure is fully custom (e.g., no Filament sub-sidebar, bespoke Blade templates).
  • You need advanced interactivity (e.g., drag-and-drop reordering, nested collapsible groups) beyond toggle functionality.
  • Your design system prohibits third-party UI components (e.g., strict CSS-in-JS or shadow DOM constraints).
  • You’re on Filament v2 or Laravel <10 (unsupported).
  • Your primary use case is mobile-first (plugin hides sub-nav on screens <768px by default).
  • You require server-side rendering only (plugin includes SPA optimizations that may add complexity).

How to Pitch It (Stakeholders)

For Executives/Stakeholders: *"This package solves two critical pain points for our Filament admin panels:

1. Upgrade Safety: If we migrate to Filament v5 (planned for Q3), this plugin ensures our sub-navigation—used in 80% of resource pages—works out-of-the-box, saving ~200 dev hours we’d otherwise spend on custom fixes.
2. User Efficiency: For teams like Support and Operations (who manage 50+ sub-items in ‘Tickets’ and ‘User Roles’), collapsible navigation reduces tab-switching by 30% in pilot tests. The dark-mode tooltips also cut support tickets about unreadable UI in night shifts.

Why now? The latest update (v1.6.0) fixes critical bugs in Filament v5 and SPAs, making it production-ready. It’s like getting a free accessibility audit and upgrade path in one. Ask: Should we enable this for the ‘Customer Portal’ (highest clutter complaints) in the next sprint?"

For Engineers/Dev Leads: *"Zero-effort upgrade for Filament v5:

• What it does: Adds a collapsible toggle to sub-navigation sidebars (e.g., ‘Create Post’ → ‘Drafts’/‘Published’ tabs). Works in v3/v4/v5 with no config.
• Key fixes in v1.6.0:
  • SPA mode: Collapsed state now persists across Livewire routes (no more desync).
  • Tooltips: CSS-only ::after elements replace JS-dependent tooltips—works in v4/v5 even if Tippy/Alpine is misconfigured.
  • Dark mode: Tooltips respect Filament’s dark class (no more white-on-white text).
  • Accessibility: Added aria-label to collapsed items.
• How to deploy:

  composer require emuniq/filament-collapsible-subnav
  

  Optional: Run php artisan collapsible-subnav:install to bundle CSS with your theme (reduces HTTP requests).
• Testing focus:
  1. Verify tooltips in dark mode (toggle CSS dark class).
  2. Test Livewire navigation state (e.g., collapse ‘Drafts’, navigate to ‘Comments’, return—should stay collapsed).
  3. Check mobile (<768px): sub-nav should hide by default.
• Risk: None. Backward-compatible with v3/v4, and v5 support is explicitly tested. Action: Add to composer.json and validate in staging."*

For Product/UX Teams: *"Proposal: Pilot collapsible sub-navigation on the ‘Content Library’ (most sub-items) to reduce cognitive load.

• Why here: This page has 12 sub-tabs (Assets, Templates, etc.), and our analytics show 40% of users abandoning it mid-task.
• Hypothesis: Collapsible nav will:
  • Reduce tab-switching by 30% (based on Filament v3 pilot data).
  • Lower support tickets about ‘lost’ UI elements (e.g., "Where did the ‘Publish’ button go?").
• Testing plan:
  1. Enable plugin on ‘Content Library’ only (use ->plugin() in ContentLibraryPanel.php for manual control).
  2. Measure:
     • Time spent navigating between tabs (pre/post).
     • Task completion rate (e.g., "Publish a post" workflow).
  3. Survey power users: "Does the collapsible nav help you find what you need faster?"
• Design ask: Should we customize the collapsed button icon (e.g., replace chevron with a custom SVG) to match our brand?"*