Sileo Livewire Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require superbyte23/sileo-livewire
   npm install sileo react react-dom @vitejs/plugin-react
   

   Update vite.config.js to include the React plugin.

2. Publish Assets:

   php artisan vendor:publish --tag=sileo-livewire-js
   

   Add the toaster to your root layout:

   <livewire:sileo-toaster position="top-right" />
   

3. First Toast: Use the SileoToastable trait in a Livewire component:

   use Superbyte23\SileoLivewire\SileoToastable;
   
   class MyComponent extends Component {
       use SileoToastable;
   
       public function showToast() {
           $this->toast('Success!', 'This is a test toast.', 'success');
       }
   }
   

Where to Look First

• Documentation: Check the GitHub README for API reference and available toast types.
• Livewire Component: Inspect SileoToastable trait methods in src/SileoToastable.php.
• JavaScript Bridge: Review resources/js/sileo-bridge.js for emitted events and payload structure.

Implementation Patterns

Usage Patterns

1. Component Integration:

   • Use the SileoToastable trait in any Livewire component to enable toasts.
   • Example workflow:

     public function submitForm() {
         if ($this->validate()) {
             $this->save();
             $this->toast('Saved!', 'Your changes have been saved.', 'success');
         } else {
             $this->toast('Error!', 'Please fix the errors below.', 'error');
         }
     }
     

2. Dynamic Toasts:

   • Pass variables dynamically:

     $this->toast('User Created', "User {$this->user->name} added successfully.", 'info');
     

3. Custom Toast Types:

   • Extend the default types (success, error, info, warning) by modifying the JavaScript bridge or publishing custom assets.

4. Positioning:

   • Change toast position via the position prop in the SileoToaster component:

     <livewire:sileo-toaster position="bottom-left" />
     

Workflows

1. Form Submission:

   • Show success/error toasts post-validation:

     public function save() {
         try {
             $this->validate();
             $this->performSave();
             $this->toast('Success', 'Data saved.', 'success');
         } catch (\Exception $e) {
             $this->toast('Error', $e->getMessage(), 'error');
         }
     }
     

2. Async Operations:

   • Use toasts for feedback during long-running tasks (e.g., file uploads):

     public function upload() {
         $this->toast('Uploading...', 'Please wait.', 'info');
         $this->dispatch('upload-started');
         // Handle upload logic...
     }
     

3. Global Toasts:

   • Trigger toasts from non-Livewire contexts (e.g., controllers) by injecting the SileoToastable trait or using a facade/service.

Integration Tips

• Vite Optimization:

  • Ensure sileo-bridge.js is imported in your main JS file (e.g., resources/js/app.js):

    import './sileo-bridge';
    

• Styling:

  • Customize toasts by overriding Sileo’s CSS variables in your global stylesheet. Example:

    .sileo-toast {
        --sileo-bg: #2d3748;
        --sileo-text: #ffffff;
    }
    

• Testing:

  • Mock the SileoToastable trait in PHPUnit tests:

    $component->expectsToast('Success', 'Test', 'success');
    

Gotchas and Tips

Pitfalls

1. JavaScript Bridge Missing:

   • Forgetting to publish the JS bridge (php artisan vendor:publish --tag=sileo-livewire-js) will result in no toasts appearing.
   • Fix: Run the publish command and ensure sileo-bridge.js is imported.

2. React/Vite Mismatch:

   • If toasts don’t render, verify:
     • @vitejs/plugin-react is included in vite.config.js.
     • react and react-dom are installed via npm.
   • Fix: Reinstall dependencies and restart Vite dev server.

3. Livewire Component Not Found:

   • If <livewire:sileo-toaster /> fails, ensure:
     • The SileoToaster component is registered (automatically done via the package).
     • The Livewire namespace is correctly configured in config/livewire.php.

4. Toast Not Showing:

   • Check browser console for errors (e.g., missing SileoToastable trait or JS bridge issues).
   • Debug: Add console.log in sileo-bridge.js to verify events are emitted.

Debugging

1. Event Listener Issues:

   • If toasts don’t trigger, verify the Livewire event listener in sileo-bridge.js is correctly set up:

     window.addEventListener('toast', (e) => {
         console.log('Toast event:', e.detail); // Debug payload
         // ... rest of the logic
     });
     

2. Payload Structure:

   • Ensure the PHP trait emits the correct payload structure:

     $this->dispatch('toast', [
         'title' => 'Title',
         'message' => 'Message',
         'type' => 'success',
     ]);
     

Tips

1. Custom Toast Types:

   • Extend the package by adding custom toast types in the JS bridge:

     // In sileo-bridge.js
     const types = {
         success: { bg: '#48bb78', icon: '✓' },
         error: { bg: '#f56565', icon: '✗' },
         custom: { bg: '#6366f1', icon: '🎨' }, // Add custom type
     };
     

2. Auto-Dismissal:

   • Control toast duration by passing a duration parameter (in milliseconds):

     $this->toast('Info', 'This will disappear in 3 seconds.', 'info', 3000);
     

3. Dark Mode Support:

   • Leverage Sileo’s built-in dark mode by adding a dark prop to the SileoToaster:

     <livewire:sileo-toaster position="top-right" dark="{{ request()->wantsDarkMode() }}" />
     

4. Performance:

   • For high-frequency toasts (e.g., real-time updates), batch events or use a queue to avoid UI jank.

5. Localization:

   • Localize toast messages by wrapping them in Laravel’s __() function:

     $this->toast('Success', __('messages.saved_successfully'), 'success');