Spotlight Laravel Package

Getting Started

Minimal Steps to First Use

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:

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

2. Trigger Spotlight Use keyboard shortcuts (CTRL/CMD + K or CTRL/CMD + /) or dispatch via Livewire/Alpine:

   // Livewire v3
   $this->dispatch('toggle-spotlight');
   

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

3. Create a Basic Command Generate a command:

   php artisan make:spotlight Logout
   

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

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

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

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

Implementation Patterns

Common Workflows

1. Command Organization Group related commands in a dedicated namespace (e.g., App\SpotlightCommands\Admin) and register them in bulk:

   // AppServiceProvider
   public function boot() {
       Spotlight::registerCommand(\App\SpotlightCommands\Admin\CreateUser::class);
       Spotlight::registerCommand(\App\SpotlightCommands\Admin\DeleteUser::class);
   }
   

2. Dependency Handling Use dependencies for multi-step actions (e.g., user creation with team selection):

   public function dependencies() {
       return SpotlightCommandDependencies::collection()
           ->add(SpotlightCommandDependency::make('team')->setPlaceholder('Select a team'));
   }
   
   public function searchTeam($query) {
       return Team::where('name', 'like', "%$query%")
           ->get()
           ->map(fn(Team $team) => new SpotlightSearchResult($team->id, $team->name, 'Team: ' . $team->name));
   }
   

3. Conditional Commands Hide/show commands based on user roles or permissions:

   public function shouldBeShown(Request $request) {
       return $request->user()->hasRole('admin');
   }
   

4. Dynamic UI Actions Emit Livewire events or open modals:

   public function execute(Spotlight $spotlight, Team $team) {
       $spotlight->emit('openModal', 'create-user', ['team_id' => $team->id]);
   }
   

5. Search Synonyms Expand discoverability with synonyms:

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

Integration Tips

• Livewire Components: Use $spotlight->emit() to trigger actions in other Livewire components.
• Alpine.js: Combine with Alpine for dynamic UI updates (e.g., toggle Spotlight from a button).
• Testing: Mock SpotlightCommand dependencies in unit tests:

  $this->partialMock(Spotlight::class, function ($mock) {
      $mock->shouldReceive('redirect')->with('/dashboard');
  });
  

Gotchas and Tips

Pitfalls

1. Shortcut Conflicts

   • Default shortcuts (CTRL/CMD + K/ /) may conflict with browser extensions or other apps.
   • Fix: Customize shortcuts in config/livewire-ui-spotlight.php:

     'shortcuts' => ['shift', 's'], // CTRL/CMD + Shift + S
     

2. Alpine.js Missing (Livewire v2)

   • Forgetting to include Alpine.js will break Spotlight functionality.
   • Fix: Add the CDN or bundle Alpine via npm.

3. Command Registration Overrides

   • Commands registered in config/livewire-ui-spotlight.php override those in AppServiceProvider.
   • Fix: Use Spotlight::registerCommandUnless() for conditional overrides.

4. Dependency Resolution Failures

   • Unresolvable dependencies (e.g., missing searchTeam method) will crash Spotlight.
   • Fix: Validate dependencies in shouldBeShown() or use try-catch in execute().

5. Livewire v2 vs. v3 Dispatch

   • Mixing dispatchBrowserEvent (v2) and dispatch (v3) will fail.
   • Fix: Use dispatch for v3 and wrap in if (method_exists($this, 'dispatch')) for backward compatibility.

Debugging Tips

• Log Commands: Add debug logs in execute() or shouldBeShown():

  \Log::debug('Executing command', ['command' => $this->name]);
  

• Check Published Views: If Spotlight renders incorrectly, publish and override views:

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

• Fuse.js Errors: If search results are missing, ensure fuse.js is loaded (check include_js config).

Extension Points

1. Custom Views Override the default Spotlight template by publishing and modifying:

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

   Key files: resources/views/vendor/livewire-ui-spotlight/spotlight.blade.php.

2. Dynamic Command Loading Load commands dynamically (e.g., from a database) by implementing a SpotlightCommandProvider interface.

3. Custom Styling Disable Tailwind CSS inclusion ('include_css' => false) and add your own CSS:

   <link rel="stylesheet" href="{{ asset('css/spotlight-custom.css') }}">
   

4. Localization Extend translations by publishing the language file:

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

   Add custom keys to resources/lang/en/spotlight.php.

5. Performance

   • Lazy-load commands: Register commands dynamically in boot() to avoid eager loading.
   • Debounce search: Use Alpine’s @debounce to optimize search queries:

     <input @input.debounce.300ms="$wire.call('search', $event.target.value)">