Spotlight Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require wire-elements/spotlight
   

   Add the Livewire directive to your layout (e.g., resources/views/layouts/app.blade.php):

   @livewire('livewire-ui-spotlight')
   

   For Livewire v2, include Alpine.js via CDN:

   <script defer src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js"></script>
   

2. First Command: Generate a basic command:

   php artisan make:spotlight Logout
   

   Edit the generated file (app/SpotlightCommands/Logout.php):

   use LivewireUI\Spotlight\SpotlightCommand;
   
   class Logout extends SpotlightCommand {
       protected string $name = 'Logout';
       protected string $description = 'Logout of your account';
   
       public function execute() {
           Auth::logout();
           redirect('/');
       }
   }
   

3. Register Command: Add the command to config/livewire-ui-spotlight.php:

   'commands' => [
       \App\SpotlightCommands\Logout::class,
   ],
   

4. Test Spotlight: Open Spotlight with Ctrl+K (or Cmd+K on Mac) and search for "Logout".

Implementation Patterns

Core Workflows

1. Command Creation:

   • Use php artisan make:spotlight for boilerplate.
   • Extend LivewireUI\Spotlight\SpotlightCommand and define:
     • $name (displayed in search results).
     • $description (tooltip text).
     • execute() (logic when command is selected).
   • Example: User management, navigation, or API-triggered actions.

2. Dynamic Commands:

   • Use shouldBeShown() to conditionally hide/show commands (e.g., role-based access):

     public function shouldBeShown(): bool {
         return auth()->user()->isAdmin();
     }
     

3. Dependency Handling:

   • Define multi-step commands with dependencies():

     public function dependencies() {
         return SpotlightCommandDependencies::collection()
             ->add(SpotlightCommandDependency::make('user')->setPlaceholder('Search for a user...'));
     }
     

   • Implement search{DependencyName}() to fetch dynamic results:

     public function searchUser($query) {
         return User::where('name', 'like', "%$query%")
             ->limit(5)
             ->get()
             ->map(fn ($user) => new SpotlightSearchResult($user->id, $user->name, 'Select user'));
     }
     

4. Integration with Livewire:

   • Emit events from execute() to trigger Livewire updates:

     public function execute(Spotlight $spotlight) {
         $spotlight->emit('showModal', ['type' => 'create-user']);
     }
     

   • Listen for Spotlight events in Livewire components:

     protected $listeners = ['showModal' => 'handleModal'];
     

5. Global Shortcuts:

   • Customize shortcuts in config/livewire-ui-spotlight.php:

     'shortcuts' => ['k', 'slash', 'shift+k'], // Adds Shift+K as a trigger
     

   • Toggle programmatically via JavaScript/Alpine:

     <button @click="$dispatch('toggle-spotlight')">Open Spotlight</button>
     

Advanced Patterns

1. Search Synonyms:

   • Add aliases for commands:

     protected array $synonyms = ['billing', 'payment', 'invoice'];
     

2. Conditional Registration:

   • Register commands dynamically in a service provider:

     Spotlight::registerCommandIf(
         auth()->check(),
         \App\SpotlightCommands\UserProfile::class
     );
     

3. Custom Views:

   • Publish and override the default Blade view:

     php artisan vendor:publish --tag=livewire-ui-spotlight-views
     

   • Modify resources/views/vendor/livewire-ui-spotlight/spotlight.blade.php.

4. Localization:

   • Publish translations:

     php artisan vendor:publish --tag=livewire-ui-spotlight-translations
     

   • Override the placeholder in resources/lang/en/spotlight.php:

     'placeholder' => 'Search actions...',
     

Gotchas and Tips

Pitfalls

1. Livewire v2 vs v3:

   • v2: Use dispatchBrowserEvent('toggle-spotlight').
   • v3: Use dispatch('toggle-spotlight').
   • Alpine: Required for v2; ensure it’s loaded before Spotlight.

2. Dependency Resolution:

   • If execute() dependencies fail, verify:
     • The dependency is registered in the container (e.g., Team model must be resolvable).
     • The search{Dependency} method returns SpotlightSearchResult objects (not raw data).

3. Command Visibility:

   • Commands must be registered (via config or Spotlight::registerCommand()) and pass shouldBeShown() if defined.
   • Debug visibility with:

     public function shouldBeShown(): bool {
         \Log::info('Checking visibility...');
         return true; // Temporarily force-show for testing
     }
     

4. CSS/JS Conflicts:

   • If Spotlight appears broken:
     • Set 'include_css' => true in config if not using Tailwind.
     • Disable 'include_js' => false and manually bundle fuse.js if using a custom build system.

5. Shortcut Conflicts:

   • Overlapping keyboard shortcuts (e.g., Ctrl+K used elsewhere) may require customizing the config or using JavaScript to intercept events.

Debugging Tips

1. Log Command Execution: Add debug logs to execute() or shouldBeShown():

   public function execute() {
       \Log::info('Logout command executed');
       Auth::logout();
   }
   

2. Inspect Search Results: Dump search{Dependency} results to verify data:

   public function searchUser($query) {
       $results = User::where('name', 'like', "%$query%")->get();
       \Log::info($results);
       return $results->map(...);
   }
   

3. Check Registration: Verify commands are loaded by inspecting the config or using:

   \LivewireUI\Spotlight\Facades\Spotlight::getCommands();
   

4. Alpine/JS Issues:

   • Ensure Alpine is loaded before Spotlight.
   • Check browser console for errors (e.g., missing fuse.js).

Extension Points

1. Custom Search Logic: Override the default search behavior by extending the Spotlight component or using middleware to filter commands.

2. Theme Customization: Modify the published Blade view to change styling or layout (e.g., add icons, adjust spacing).

3. Event Listeners: Listen for Spotlight events globally (e.g., in a service provider) to log usage or trigger analytics:

   \LivewireUI\Spotlight\Facades\Spotlight::on('command-executed', function ($command) {
       \Log::info("Command executed: {$command->getName()}");
   });
   

4. Dynamic Command Loading: Fetch commands via API (e.g., for admin panels) by implementing a custom command resolver.