Filament Workspace Tabs Laravel Package

Technical Evaluation

Architecture Fit

• Pros:
  • Seamless Filament Integration: Designed specifically for Filament v4/v5, leveraging its TOPBAR_AFTER hook for minimal template disruption. Aligns with Filament’s SPA/Livewire architecture (supports wire:navigate).
  • Client-Side State Management: Uses localStorage + Alpine.js $persist() for persistence, reducing server-side complexity. Ideal for admin panels where user context (e.g., open tabs) is ephemeral.
  • Modular Design: Plugin-based approach (via WorkspaceTabsPlugin::make()) enables granular configuration (e.g., disabling drag/reorder) without monolithic changes.
  • UX Synergy: Mimics browser-native tab behavior (drag-and-drop, keyboard shortcuts, pinned tabs), reducing cognitive load for power users.
• Cons:
  • Tight Coupling to Filament: Limited utility outside Filament panels (e.g., no standalone Laravel Blade/Inertia support). Risk of drift if Filament’s core APIs (e.g., Livewire.navigate) change.
  • Client-Side Dependencies: Relies on Alpine.js and SortableJS, adding ~50KB to the frontend bundle. May conflict with existing Filament plugins using similar libraries (e.g., drag-and-drop components).

Integration Feasibility

• Low Barrier to Entry:
  • 1-Liner Installation: composer require + Tailwind source inclusion.
  • Zero Template Changes: Hooks into Filament’s existing render pipeline (TOPBAR_AFTER).
  • Backward Compatibility: Supports Laravel 11+ and PHP 8.2+, aligning with modern stacks.
• Potential Friction Points:
  • Tailwind Scanning: Requires explicit @source directive in theme.css (may need npm run build in CI/CD pipelines).
  • LocalStorage Scope: Defaults to panel-scoped keys (filament_workspace_tabs:{panel_id}), which is correct but may need customization for multi-panel apps.
  • SPA Mode Dependency: Full functionality assumes Filament’s SPA mode (->spa()). Traditional server-side navigation may behave differently (e.g., page reloads on tab switch).

Technical Risk

Key Questions

1. Filament Ecosystem Compatibility:
   • Does your Filament setup use ->spa()? If not, how critical is SPA-like navigation for your use case?
   • Are you using other plugins that modify the topbar or rely on Alpine.js/SortableJS?
2. Multi-Panel Support:
   • Do you need cross-panel tab persistence (e.g., tabs open in Panel A should reopen in Panel B)? If so, the default panel-scoped keys may require adjustment.
3. Customization Needs:
   • Will you need to exclude specific URLs (e.g., /admin/analytics) from tab tracking?
   • Should pinned tabs have additional UI/UX changes (e.g., icons, tooltips)?
4. Offline/Privacy Compliance:
   • Does your app require localStorage opt-outs (e.g., for GDPR)? The package lacks explicit controls for this.
5. Scaling:
   • What’s the expected maximum concurrent tabs per user? The default maxTabs(20) may need adjustment for power users.

Integration Approach

Stack Fit

• Ideal For:
  • Filament v4/v5 Admin Panels: Especially those with complex workflows (e.g., multi-step forms, dashboards with frequent navigation).
  • SPA-Heavy Applications: Leverages wire:navigate for seamless transitions, reducing full-page reloads.
  • Power User Workflows: Teams using Filament for internal tools where tab management (pinning, reordering) improves productivity.
• Less Suitable For:
  • Public-Facing Apps: LocalStorage persistence may not align with privacy requirements.
  • Non-Filament Projects: Zero utility outside Filament panels without significant refactoring.
  • High-Security Environments: Context menus and keyboard shortcuts could introduce UX attack surfaces (e.g., tabnabbing).

Migration Path

1. Pre-Integration Checks:
   • Verify Filament version (composer show filament/filament) and PHP/Laravel compatibility.
   • Audit existing theme.css for Tailwind conflicts (e.g., duplicate @source directives).
   • Test in a staging environment with ->spa() enabled if applicable.
2. Installation:

   composer require wezlo/filament-workspace-tabs
   

   Update resources/css/filament/{panel}/theme.css:

   @source '../../../../vendor/wezlo/filament-workspace-tabs/resources/views/**/*';
   

   Rebuild assets:

   npm run build
   

3. Configuration: Register the plugin in your panel provider (e.g., app/Providers/Filament/AdminPanelProvider.php):

   public function panel(Panel $panel): Panel {
       return $panel->plugins([
           WorkspaceTabsPlugin::make()
               ->maxTabs(30)
               ->excludeUrls(['/admin/reports/export'])
               ->contextMenu(true),
       ]);
   }
   

4. Post-Integration Testing:
   • Functional: Test tab creation, pinning, drag-and-drop, and context menus.
   • Persistence: Verify tabs survive page reloads and browser restarts.
   • Edge Cases: Check behavior with:
     • Middle-click/Ctrl+click navigation.
     • Keyboard shortcuts (Ctrl+W).
     • Recently closed tabs dropdown.
     • Concurrent sessions (if using shared storage).

Compatibility

• Filament Plugins:
  • High Risk: Plugins that modify the topbar (e.g., custom headers) or use Alpine.js/SortableJS may conflict. Test with:
    • filament-spa
    • filament-notifications
    • Any custom topbar plugins.
  • Mitigation: Wrap plugin registration in a feature flag or test in isolation.
• Browser Support:
  • Relies on modern APIs (localStorage, document.title). No known issues with evergreen browsers (Chrome, Firefox, Edge, Safari).
• Livewire/Inertia:
  • Fully compatible with Filament’s SPA mode. Traditional Livewire pages will work but may not support smooth transitions.

Sequencing

1. Phase 1: Core Integration (1–2 days):
   • Install, configure, and test basic tab functionality.
   • Focus on: Tab creation, switching, and persistence.
2. Phase 2: Advanced Features (1 day):
   • Enable drag-and-drop, context menus, and pinned tabs.
   • Customize maxTabs, excludeUrls, etc.
3. Phase 3: UX Refinement (1–2 days):
   • Adjust Tailwind styles to match your theme.
   • Test keyboard shortcuts and edge cases (e.g., tab overflow).
4. Phase 4: Rollout (1 day):
   • Deploy to staging, gather feedback.
   • Monitor for performance regressions or conflicts.

Operational Impact

Maintenance

• Proactive:
  • Dependency Updates: Monitor wezlo/filament-workspace-tabs for Filament v5+ compatibility. Subscribe to the repo for breaking changes.
  • Tailwind/CSS: Rebuild assets (npm run build) after Filament or package updates that modify the topbar.
  • LocalStorage Quotas: Warn users if they approach maxTabs limits (e.g., via a tooltip).
• Reactive:
  • Plugin Conflicts: Maintain a matrix of tested Filament plugins to avoid integration debt.
  • User Training: Document keyboard shortcuts (e.g., Ctrl+W) and context menu options for non-technical users.

Support

• Common Issues:
  • Tabs Not Persisting: Clear localStorage or check persistKey configuration.
  • Drag-and-Drop Flickering: Ensure no overlapping Alpine.js event handlers.
  • Context Menu Not Showing: Verify contextMenu(true) is set and no CSS is hiding the menu