Spotlight Laravel Package

Product Decisions This Supports

• Build vs. buy for a command palette. A hand-rolled ⌘K palette is typically 1–3 weeks of frontend work (focus trapping, keybind management, fuzzy matching, result ranking) plus permanent ownership of that surface. This package delivers the shell, keybindings, fuzzy search (Fuse.js), and result rendering for the cost of a Composer require and one Blade directive — a clear buy unless the palette is a core differentiator.
• Investing in power-user velocity. The palette converts multi-click navigation ("Settings → Billing → Subscription") into a single keystroke-plus-query. This is a cheap lever on a metric PMs already track: time-to-task for repeat users, and reduction in menu-driven support tickets.
• Collapsing multi-step workflows into one surface. The dependencies() API chains prompts (pick a team → search for a user → execute), with each step able to query against the prior selection. That turns a 4-page wizard into one box. This is the package's most under-appreciated product capability — it's workflow automation, not just navigation.
• Feature discoverability and onboarding. Commands are self-describing ($name, $description, $synonyms), so a newly shipped feature can be surfaced in the palette without adding nav items, hero banners, or dashboard cards. Synonyms let users find features by the words they actually use ("credit card" → Billing Settings), which is a direct input to naming and IA decisions.
• Safe exposure across roles and plans. shouldBeShown() resolves the container (so Request, the authenticated user, gates/policies, and subscription state are all available), meaning one palette can be shipped to all users while commands are filtered per-permission. That supports tiered packaging (free vs. paid command sets) without forking the UI.
• Roadmap sequencing for keyboard-first UX. Adopting this early creates a cheap home for every subsequent "quick action" the team ships, which biases the roadmap toward composable actions rather than more pages — a useful forcing function on IA.
• Internal tools and admin panels. Highest ROI segment: operators and support staff live in these apps, work from memory, and value speed over visual polish.

Adoption risks to price in: the palette is coupled to Livewire (v2/v3) and Tailwind, and the fuzzy matching is client-side, so it suits a curated set of tens-to-hundreds of commands — not global search across large content sets. It's a single-maintainer MIT package (~950 stars), so budget a plan for vendoring or replacing the component shell if maintenance lags.

When to Consider This Package

Adopt when:

• The app is Laravel + Livewire (v2 or v3) and already uses Tailwind, or you're willing to enable the bundled CSS.
• Your users are repeat/power users — internal ops, admin, support, developer tools, or a SaaS with a dense feature set.
• You can express the highest-value actions as discrete commands (navigate, create, toggle, invite, export) rather than free-form content search.
• You want a permission-aware surface and can define shouldBeShown() per command.
• You want a fast, low-risk pilot: one directive in the layout, one or two commands, ship it behind a flag and measure.

Look elsewhere when:

• The frontend isn't Livewire. React/Vue/Inertia teams should use a native palette primitive (e.g. cmdk, kbar) rather than bolting Livewire into a non-Livewire app — the coupling cost outweighs the shortcut.
• You need true global search across user-generated content (documents, records, messages). Use Laravel Scout + Meilisearch/Typesense, and consider the palette as the entry point that hands off to a server-side search page.
• Accessibility is a hard procurement requirement. The component's ARIA/keyboard behavior and screen-reader support should be audited by your own team before it becomes the only path to a function.
• You need built-in command telemetry, ranking overrides, usage analytics, or A/B testing of results — you'll be instrumenting this yourself.
• The palette is a flagship, differentiated part of the product, or you're on a maintenance model where single-maintainer dependencies require a fork-and-own commitment you can't fund.
• Your command set is large and highly dynamic per-user (thousands of entries); the client-side Fuse.js approach will need server-side filtering workarounds.

How to Pitch It (Stakeholders)

For executives (one paragraph): Spotlight is a drop-in command palette for our Laravel/Livewire app — the ⌘K search-and-act bar users already know from Slack, Notion, and Linear. Integration is measured in hours, not sprints: one Blade directive, one config entry, and a short command class per action. It replaces multi-click navigation with a single keystroke and query, gives every future feature a zero-cost discovery surface, and can be permission-filtered so the same palette ships safely to every role and plan. It's MIT-licensed with no vendor contract, so the downside is bounded: if it doesn't earn its place, we remove one directive. We should treat it as a scoped pilot behind a feature flag, instrumented against time-to-task and palette adoption, and decide on expansion after one release cycle.

For engineering: Small, well-documented surface — extend SpotlightCommand, define $name/$description/$synonyms, and optionally execute(), dependencies(), and shouldBeShown(); dependencies resolve from the container, so existing services and policies are reusable. Registration is via config or Spotlight::registerCommand() in a service provider, which means we can gate command sets by environment or plan without touching the component. Costs are explicit: it's Livewire-coupled (a future move to Inertia/React means rewriting the palette shell, not the commands), Tailwind-coupled for styling, and client-side fuzzy search — so we keep the command list curated and route heavy search to our existing backend. Vendor the package or pin the version and add a smoke test around the palette's open/execute path, given the single-maintainer footprint.

Success criteria for the pilot: palette opened by ≥X% of weekly active users, measurable reduction in time-to-complete for 2–3 named tasks, and no increase in permission-related support tickets.