Filament Search Spotlight Laravel Package

Getting Started

1. Installation:

   composer require wezlo/filament-search-spotlight
   

   Register the plugin in your Filament panel:

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

2. First Use Case:

   • Press ⌘K (or configured shortcut) to open the Spotlight overlay.
   • Type to search across records, resources, pages, and actions (auto-generated for resources with a create page).
   • Navigate with arrow keys, select with Enter, or close with Esc.

3. Where to Look First:

   • Config: Publish the optional config file:

     php artisan vendor:publish --tag=filament-search-spotlight-config
     

   • Tailwind: Ensure your theme.css scans the package’s views:

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

     Rebuild with npm run build.

Implementation Patterns

Core Workflow

1. Plugin Registration: Configure globally or per-panel using the fluent API:

   FilamentSearchSpotlightPlugin::make()
       ->keyBinding('mod+k')
       ->placeholder('Jump to…')
       ->excludeResources([AuditLogResource::class])
       ->action(SpotlightAction::make('custom-action')->url('/path'));
   

2. Search Categories:

   • Records: Auto-populated from GlobalSearchProvider (attaches resource icons).
   • Resources/Pages/Actions: Pre-built categories with fuzzy matching.
   • Custom Categories: Implement Category contract (e.g., for settings or reports):

     class MyCategory implements Category {
         public function search(string $query, int $limit): array { ... }
     }
     

3. Actions:

   • Global Registry: Register actions app-wide (e.g., in AppServiceProvider):

     SpotlightAction::make('clear-cache')->register();
     

   • Panel-Scoped: Override or extend via the plugin:

     ->action(SpotlightAction::make('log-out')->url(fn () => filament()->getLogoutUrl()))
     

4. Exclusions:

   • Hide resources from search/auto-actions:

     ->excludeResources([Resource::class])
     

   • Disable default categories:

     ->records(false)->actionsEnabled(false)
     

Integration Tips

• Disable Default Search: Replace Filament’s top-bar search with:

  ->disableDefaultGlobalSearch()
  

• Keyboard Shortcuts: Customize bindings (Mousetrap syntax):

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

• Styling: Override CSS via maxWidth() or inline styles (not purged by Tailwind):

  ->maxWidth('40rem')
  

• Testing: Run feature tests in your app:

  php artisan test --compact tests/Feature/FilamentSearchSpotlight
  

Gotchas and Tips

Pitfalls

1. Tailwind Purging:

   • Issue: Utility classes may disappear if theme.css doesn’t scan the package’s views.
   • Fix: Add @source directive and rebuild:

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

2. Resource Exclusions:

   • Issue: Excluding a resource hides it from Records, Resources, and auto-generated Create actions.
   • Fix: Use excludeResources() or disable Create actions separately:

     ->excludeResources([Resource::class]) // Hides all
     ->disableCreateActions() // Only hides Create actions
     

3. Action Overrides:

   • Issue: Panel-scoped actions replace global registry actions with the same name.
   • Fix: Use overrideActions() to hide without replacing:

     ->overrideActions(['legacy-action'])
     

4. LocalStorage Dependencies:

   • Issue: Recent/pinned items persist client-side only. Multi-tab or shared-session setups may show stale data.
   • Fix: Clear localStorage on logout if needed (client-side JS).

5. Fuzzy Matching:

   • Issue: Search relies on str_contains() for fuzzy matching. Complex queries may yield unexpected results.
   • Fix: Extend a category’s search() method for custom logic (e.g., regex or library like fuzzy-matcher).

Debugging

• Empty Results:

  • Verify GlobalSearchProvider is implemented for records.
  • Check excluded_resources in config/plugin.
  • Test categories individually by disabling others.

• Styling Issues:

  • Inspect the overlay’s HTML/CSS (right-click → "Inspect").
  • Ensure maxWidth is set and not overridden by Tailwind.

• Keyboard Shortcuts:

  • Confirm no JavaScript conflicts (e.g., other mod+k handlers).
  • Test in incognito mode to rule out cached localStorage.

Extension Points

1. Custom Categories:

   • Implement Category contract for new data sources (e.g., API endpoints):

     class ApiCategory implements Category {
         public function search(string $query, int $limit): array {
             return collect($this->fetchFromApi($query))
                 ->map(fn ($item) => new SpotlightResult(
                     id: 'api:'.$item['id'],
                     title: $item['name'],
                     url: $item['url'],
                     // ...
                 ));
         }
     }
     

2. Dynamic Actions:

   • Use closures for URLs or labels:

     ->action(SpotlightAction::make('dynamic-action')
         ->url(fn () => route('admin.user.edit', ['user' => auth()->id()]))
     )
     

3. Translations:

   • Extend the package’s language files (e.g., resources/lang/en/spotlight.php) or publish them:

     php artisan vendor:publish --tag=filament-search-spotlight-lang
     

4. Recent/Pinned Logic:

   • Override client-side behavior by extending the package’s JS (e.g., resources/js/filament-search-spotlight.js).

Pro Tips

• Power User Shortcuts: Add frequently used actions to the global registry:

  SpotlightAction::make('toggle-dark-mode')
      ->keywords(['dark', 'light'])
      ->url(fn () => route('admin.settings.toggle-theme'))
      ->register();
  

• Panel-Specific Config: Use the fluent API to override global settings per panel:

  FilamentSearchSpotlightPlugin::make()
      ->placeholder('Admin: Jump to…')
      ->keyBinding('ctrl+shift+k')
  

• Performance: Limit results per category to avoid UI lag:

  ->resultLimitPerCategory(5)
  

• Accessibility: Ensure keyboard navigation works (arrow keys, Enter, Esc) and test with screen readers. The package handles this out-of-the-box, but custom categories should follow these patterns.