Filament Search Spotlight Laravel Package

Getting Started

1. Installation:

   composer require wezlo/filament-search-spotlight
   

   Register the plugin in your Filament panel:

   FilamentSearchSpotlightPlugin::make(),
   

2. First Use Case:

   • Press ⌘K (or your configured shortcut) to open the spotlight overlay.
   • Start typing to search across records, resources, pages, and actions (if enabled).
   • Navigate with arrow keys, select with Enter, and close with Esc.

3. Tailwind Setup (if applicable): Add the package’s views to your Tailwind scan:

   @source '../../../../vendor/wezlo/filament-search-spotlight/resources/views/**/*';
   

   Rebuild assets (npm run build or npm run dev).

Implementation Patterns

1. Basic Integration

• Default Usage: Register the plugin in your panel’s PanelProvider:

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

  This enables all built-in categories (records, resources, pages, actions) with default settings.

• Custom Shortcut:

  FilamentSearchSpotlightPlugin::make()
      ->keyBinding('ctrl+k') // Override default ⌘K
  

2. Configuring Categories

• Toggle Categories:

  FilamentSearchSpotlightPlugin::make()
      ->records()          // Show records (default: true)
      ->resources(false)   // Hide resources
  

• Replace Entire Category List:

  ->categories([CustomCategory::class, RecordsCategory::class])
  

3. Adding Actions

• Global Actions (app-wide):

  // In AppServiceProvider::boot()
  SpotlightAction::make('clear-cache')
      ->label('Clear Cache')
      ->keywords(['cache', 'flush'])
      ->url(route('cache.clear'))
      ->register();
  

• Panel-Specific Actions:

  FilamentSearchSpotlightPlugin::make()
      ->action(
          SpotlightAction::make('log-out')
              ->label('Log Out')
              ->icon('heroicon-o-arrow-right-on-rectangle')
              ->url(fn () => filament()->getLogoutUrl())
      )
  

4. Excluding Resources

• Hide specific resources from records and resources categories:

  ->excludeResources([AuditLogResource::class])
  

5. Disabling Default Search

• Replace Filament’s top-bar global search with Spotlight:

  ->disableDefaultGlobalSearch()
  

6. Custom Categories

• Implement the Category contract:

  class SettingsCategory implements Category {
      public function search(string $query, int $limit): array {
          return collect($this->settings)
              ->filter(fn ($item) => str_contains(strtolower($item['name']), strtolower($query)))
              ->map(fn ($item) => new SpotlightResult(
                  id: 'settings:'.$item['id'],
                  title: $item['name'],
                  url: route('admin.settings.edit', $item['id']),
              ))
              ->take($limit)
              ->values()
              ->all();
      }
  }
  

• Register it:

  ->categories([SettingsCategory::class])
  

7. Styling

• Override the overlay’s max width:

  ->maxWidth('40rem')
  

• Custom placeholder text:

  ->placeholder('Quick search…')
  

Gotchas and Tips

Pitfalls

1. Tailwind Purging:

   • If using a compiled Tailwind theme, ensure the package’s views are scanned (see Getting Started).
   • Utility classes like .spotlight-overlay may be purged otherwise.

2. Resource Exclusion:

   • Excluding a resource (->excludeResources()) also hides its auto-generated "Create {Resource}" action.
   • To disable only the action, use ->disableCreateActions().

3. Action Overrides:

   • Plugin-scoped actions automatically override global registry actions with the same name.
   • Use ->overrideActions(['action-name']) to hide a global action without replacing it.

4. LocalStorage Dependencies:

   • Recent/pinned items are stored in localStorage. If your app uses iframes or multiple windows, behavior may vary.
   • No server-side persistence means these lists reset on browser clear or profile switch.

5. Keyboard Conflicts:

   • Default binding (mod+k) may conflict with other apps (e.g., VS Code). Test thoroughly.
   • Use an array for complex bindings:

     ->keyBinding(['mod+k', 'ctrl+k'])
     

6. Performance with Large Datasets:

   • The Records category delegates to Filament’s GlobalSearchProvider, which may impact performance for resources with many records.
   • Limit results per category with:

     ->resultLimitPerCategory(5)
     

Debugging Tips

1. Check Console for Errors:

   • Open DevTools (F12) and monitor the console for JavaScript errors (e.g., missing Tailwind classes).

2. Verify Plugin Registration:

   • Ensure the plugin is registered after Filament’s core plugins in your PanelProvider.

3. Test Action URLs:

   • Use dd() or dump() in action URL closures to debug routing issues:

     ->url(fn () => dd(route('admin.cache.clear')))
     

4. Inspect LocalStorage:

   • Check localStorage for spotlight.recent/spotlight.pinned to verify recent items persistence.

5. Disable Categories Incrementally:

   • Temporarily disable categories to isolate issues:

     ->records(false)
     ->resources(false)
     

Extension Points

1. Custom Result Rendering:

   • Override the SpotlightResult class or extend it to add metadata (e.g., badges, timestamps).

2. Dynamic Action Registration:

   • Register actions dynamically in a service provider based on user roles or permissions:

     if (auth()->user()->isAdmin()) {
         SpotlightAction::make('admin-dashboard')->url('/admin')->register();
     }
     

3. Server-Side Recent Items:

   • Extend the package to sync recent items to a database if needed (requires custom logic).

4. Multi-Panel Support:

   • Register the plugin in multiple panels with panel-specific configurations:

     FilamentSearchSpotlightPlugin::make()
         ->keyBinding('mod+shift+k')
         ->placeholder('Panel B Search')
     

5. Testing:

   • Use the provided test structure to write panel-specific tests:

     php artisan test --compact tests/Feature/FilamentSearchSpotlight
     

   • Mock actions or categories in tests:

     $this->actingAs($user)
         ->spotlight()
         ->search('test')
         ->assertSee('Expected Result');