Swippable Notification Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require sanzgrapher/swippable-notification
   

2. Register Plugin: Add Sanzgrapher\SwippableNotification\SwippableNotification::make() to your PanelProvider's plugins() array.

   ->plugins([
       SwippableNotification::make(),
   ])
   

3. Test Immediately: Trigger any Filament notification (e.g., Notification::make()->success()) and swipe left/right to dismiss.

First Use Case

Replace traditional click-to-dismiss notifications with swipe gestures in:

• Admin dashboards (e.g., post creation success).
• User feedback (e.g., "Profile updated").
• Error handling (e.g., validation failures).

Implementation Patterns

Core Workflows

1. Zero-Configuration Integration:

   • No manual setup for individual notifications; all Filament notifications inherit swipe functionality.
   • Ideal for rapid prototyping or legacy systems where notifications are already implemented.

2. Customizing Swipe Behavior (Advanced):

   • Override default thresholds (80px) via plugin configuration:

     SwippableNotification::make()
         ->swipeThreshold(100) // Custom threshold in pixels
         ->swipeDirection('left') // Restrict to left-only swipes
     

   • Extend the plugin by publishing and modifying its assets:

     php artisan vendor:publish --tag=swippable-notification-assets
     

3. Conditional Activation:

   • Disable swipes for specific notifications using a data-swippable="false" attribute:

     Notification::make()
         ->success()
         ->extraAttributes(['data-swippable' => 'false'])
     

4. Mobile-First Development:

   • Prioritize touch events in responsive designs (plugin handles this natively).
   • Test swipe gestures on mobile devices early in development.

Integration Tips

• Filament Widgets: Use with Notification::make() in widgets (e.g., Resources\Pages\Dashboard.php).
• API Responses: Pair with Notification::make() in API controllers for user feedback.
• Third-Party Packages: Works alongside other Filament plugins (e.g., filament-notifications).

Gotchas and Tips

Pitfalls

1. Threshold Sensitivity:

   • Default 80px threshold may feel too sensitive on high-DPI screens. Adjust via configuration.
   • Test on both desktop (mouse drag) and mobile (touch) to ensure consistency.

2. Conflicting CSS:

   • Avoid overriding Filament’s notification styles (e.g., z-index, pointer-events) to prevent swipe interference.
   • Debug with browser dev tools if swipes feel sluggish (check for touch-action: none conflicts).

3. Database Notifications:

   • Swipe functionality applies to displayed database notifications. Ensure notifications are fetched and rendered via Filament’s Notifications widget.

4. Edge Cases:

   • Small Screens: Swipes may trigger unintentionally on narrow viewports. Test on devices < 320px width.
   • Keyboard Navigation: Screen readers may ignore swipe gestures. Ensure accessibility compliance with aria-live regions.

Debugging

• Console Logs: Check for errors in browser console (e.g., missing event listeners).
• Plugin Isolation: Temporarily disable other Filament plugins to rule out conflicts.
• Asset Compilation: Run npm run dev if customizing CSS/JS after publishing assets.

Extension Points

1. Custom Animations: Modify the plugin’s JavaScript to change swipe animations (e.g., fade-out instead of slide).

   // resources/js/swippable-notification.js
   this.element.style.transition = 'opacity 0.3s';
   

2. Event Hooks: Listen for swipe events globally:

   document.addEventListener('swippable:swiped', (e) => {
       console.log('Swiped notification:', e.detail.notificationId);
   });
   

3. Server-Side Logic: Use the swiped event to trigger server actions (e.g., log dismissals):

   // In a Filament resource/page
   $this->registerScripts([
       'swippable-notification' => 'path/to/custom-script.js',
   ]);
   

4. Localization: Override cursor feedback text (e.g., "Drag to dismiss") via language files:

   // resources/lang/en/swippable.php
   {
       "drag_to_dismiss": "Swipe to close"
   }