Filament Spotlight Laravel Package

Getting Started

This is a first public release (v0.1.0) of a Spotlight-style command palette for Filament v5 panels. Treat it as an early-adopter package: the feature surface is already broad (pluggable sources, recents, a11y, localization), but the API has no stability guarantee yet.

Minimal path to a working palette:

1. Require the package: composer require takashato/filament-spotlight:^0.1.
2. Publish and run the recents migration — it is publishable, not auto-loaded, so recents will not work until you do. Publish the config in the same step.
3. Register SpotlightPlugin on each panel you want the palette in (typically in your PanelProvider's panel() method, alongside your other plugins).
4. Run php artisan migrate, then hit Cmd/Ctrl+K in the panel.

Where to look first:

• config/spotlight.php — the fastest way to understand what is tunable (source registration, recents cap, keyboard shortcut, locale behaviour).
• The SpotlightSource contract and Result DTO — these define everything you will extend.
• FilamentResourceSource — the reference implementation. Read it before writing your own source; it establishes the conventions for query handling, authorization, and handler construction.

First real use case: navigation and record-jumping. The built-ins (FilamentResourceSource, NavigationSource) give you global search across resources plus panel navigation with no custom code. Once that is live, the Tab-activated per-row Filament actions in the resource source are the feature that typically earns adoption — it turns "find the record" and "do the thing to the record" into one keyboard flow instead of two.

Implementation Patterns

Multi-panel registration. Register the plugin per panel rather than globally. Each panel has its own navigation and resource set, so a shared source list will surface results a user cannot act on. If you run admin + tenant panels, configure sources per panel.

Writing a custom source. Implement SpotlightSource, return a collection of Result objects, and register it on the plugin. The practical pattern:

• Keep the source focused on matching and authorization. Do not do side effects here.
• Resolve the current user from the source's context, not from a global, so recents and permission re-validation behave correctly.
• Return results in a stable, deterministic order — recents interleaving is easier to reason about if your own ordering does not shuffle between keystrokes.

Choosing a Handler. The factory covers four shapes, and picking the right one is most of the integration work:

• url — for internal navigation. Subject to same-origin validation, so use relative paths or same-host URLs.
• event — for dispatching a browser/Livewire/Alpine event. Payloads are restricted to scalars.
• modal — for opening a Filament action or modal from a result.
• callback — for arbitrary server-side or class-level logic that does not fit the above.

Recents as a UX layer, not a security layer. Per-user recents with LRU eviction and permission re-validation means the palette filters entries the user can no longer access. That is a good default, but it is a display guarantee — still enforce policies at the handler destination. A stale URL that survives re-validation because the policy changed shape (rather than the permission being revoked) will still resolve.

Localization and RTL. en and vi ship out of the box. If you support other locales, plan to add translations early rather than shipping a partially localized palette; the combobox labels and the mobile close button are the strings that matter for the WCAG claims to hold in your language.

Testing. Assert on sources in isolation (given a query and a user, which Results come back) rather than driving the whole palette through the browser. The handler validation layer is worth a dedicated test: it is the component most likely to silently drop a result you expected to see.

Gotchas and Tips

• 0.x versioning. Pin ^0.1 and read the changelog before every minor bump. Pre-1.0 releases from a single maintainer routinely ship breaking changes marked as minor.
• Filament v5 only. There is no v3/v4 compatibility path stated. If your panels are on v4, this package is not an option yet, and mixing versions across panels is not viable.
• Publishable migration is a trap. The most common first-run failure will be a palette that loads but records no recents, or throws on write, because the migration was never published. Check this before filing a bug.
• Same-origin URL validation. Absolute URLs to external hosts will be rejected. If you need to link out, route through event or callback rather than fighting the validator.
• Scalar-only payloads. No arrays or objects in event payloads. Flatten, or pass an identifier and resolve the rest on the receiving side.
• Cmd/Ctrl+K collides. It conflicts with browser-level shortcuts in some contexts, with other palette packages, and — depending on your Filament version — with Filament's own global search modal. Bind one thing to that chord per panel.
• Tab for row actions is unconventional. It diverges from the browser's normal tab-navigation contract. It works, but it will surprise users who tab out of the input expecting focus to move. Consider documenting it in your own onboarding rather than relying on discovery.
• Source cost per keystroke. Sources run on input, not on submit. Any source doing a non-trivial query needs a cheap pre-filter (minimum query length, LIMIT, indexed columns). This is the most likely place to introduce a latency regression.
• Callback serialization. If callback handlers are serialized into the palette payload, closures capturing non-serializable state will fail. Prefer class strings or static methods until you have confirmed the mechanism in source.
• Debugging rejected results. If a result does not appear, the failure is usually one of: source not registered on this panel, authorization filtering in the source, or handler payload validation silently discarding it. Check the browser console for rejected events before assuming a matching bug.
• Verify before depending on it. The release notes do not state whether translations are publishable, what the recents cap defaults to, whether the plugin supports per-panel source ordering, or what the package's test coverage looks like. Read the source for these before designing around them.
• Extension points worth knowing: the SpotlightSource contract (custom result types), the Handler factory (the natural place to want a fifth handler type), and config/spotlight.php (where a source registry likely lives). These three are where you will spend your integration effort.