Nova Pill Filter Laravel Package

Technical Evaluation

Architecture fit Nova filters are a first-class, documented extension point (Laravel\Nova\Filters\Filter), so this package occupies a low-blast-radius seam in the application. It is a presentation-layer concern only — a PHP filter class (options() / apply()) paired with a small Vue component that renders the options as clickable pills instead of a dropdown. It does not touch models, migrations, service container bindings, or auth. For a TPM this is close to the ideal shape of a third-party dependency: additive, reversible, and confined to the admin surface.

The one architectural wrinkle is the namespace: the package is published as shllghst/nova-pill-filter but the repository lives under mathieufrh, which suggests a fork or an ownership handoff. That is a provenance question, not a code question, but it should be resolved before adoption (see Key Questions).

Integration feasibility High. Expected path is a single composer require, Laravel package auto-discovery of the service provider, nova:publish for the compiled assets, then extending the base filter class in app/Nova/Filters and overriding options() and apply(). Realistic effort for a developer already fluent in Nova: half a day including verification, well under a sprint.

The feasibility blocker is version alignment, not complexity. Nova's front-end moved from Vue 2 (Nova 3) to Vue 3 (Nova 4), and the filter component contract changed with it. A single release dated 2023-06-09 likely targets one side of that line. If the target is Nova 5, assume it does not work until proven otherwise.

Technical risk

• Abandonment risk (high): 0 stars, 0 dependents, single maintainer, no release in over a year and a half. There is no community to catch regressions, and no signal that a Nova upgrade will be absorbed upstream.
• Version drift risk (high): the package is pinned to a Nova major and a Vue major by construction. Nova upgrades are the single most likely event to break it.
• Supply chain risk (low-moderate): MIT, tiny surface area, but unvetted maintainer identity and a namespace/repo mismatch warrant a read of the source before it enters the lockfile.
• Accessibility risk (moderate): pill UIs frequently ship as styled <div>s with click handlers and no keyboard or ARIA affordances. If the admin panel falls under an accessibility obligation, verify before committing.
• Mitigating factor: the package is small enough to fully audit and, if necessary, vendor into the repo. The downside is bounded at "we reimplement a 50–150 line component," which is near-zero cost.

Key questions

1. Which Nova major versions does composer.json constrain, and does it match our installed Nova release?
2. Does the package ship prebuilt/compiled JS assets, or does it require an npm build step against our Nova tooling?
3. Is the pill component Vue 2 or Vue 3, and does it depend on Nova's internal component library (which is not a public API and breaks between minors)?
4. Does it support dark mode, keyboard navigation, and screen-reader labels?
5. Single-select or multi-select, and does it support option counts/badges (a common requirement that pill filters are chosen for)?
6. Is the namespace/repo discrepancy a fork of an upstream package, and if so, what is the upstream's state?
7. Does apply() compose correctly with Nova lenses and with other active filters?

Integration Approach

Stack fit Fits cleanly if the application is on Laravel with Nova and the Nova version matches. If we are not on Nova, this package has no value — it is not a general-purpose filter component and cannot be lifted into a custom admin UI without a rewrite. Confirm Nova is a deliberate part of the platform strategy before spending any time here.

Migration path There is no data migration and no schema change; this is purely additive UI. The reverse migration is equally cheap: remove the filter from the resource's filters() method and drop the dependency. This is the strongest argument for trying it — the exit cost is effectively zero. Plan the integration so that this stays true: do not let the pill filter become the only way a user can reach a given query state.

Compatibility Treat compatibility as a gate, not a task. Concretely: read composer.json for the Nova constraint, inspect the shipped JS for Vue 2 vs Vue 3 idioms, and confirm asset registration in the service provider. If any of those three is ambiguous, stop and reimplement in-house rather than reverse-engineering someone else's abandoned component.

Sequencing

1. Spike (1–2 days): install on a branch, wire one filter to one low-traffic resource, verify rendering, filtering, dark mode, keyboard use, and interaction with a second active filter. Record the Nova/Vue versions tested.
2. Decision gate: if the spike passes and the source audit is clean, adopt as a pinned dependency. If it fails or is ambiguous, reimplement — the component is small enough that a reimplementation is cheaper than a debugging relationship with an unmaintained repo.
3. Pin and document: exact version in composer.lock, plus a short ADR noting the Nova/Vue versions validated and the upgrade trigger that forces a re-check.
4. Rollout: apply to the remaining resources only after the first has run a release cycle without incident.

If we adopt, adopting by vendoring the source into our repo is defensible and probably preferable: it removes the abandonment risk entirely, keeps the MIT license intact, and costs us nothing we weren't already accepting.

Operational Impact

Maintenance Budget for owning this outright, regardless of the dependency decision. The realistic steady-state cost is near zero — the code is small and the filter API is stable — but the responsibility transfers to us. The recurring cost is an annual re-verification against each Nova upgrade, which is a checklist item, not a project.

Support No SLA, no vendor, no maintainer commitment. Support surface is GitHub issues on a repo with zero stars and zero dependents, which in practice means no support. This is acceptable only because the failure mode is cosmetic and the fallback is trivially available. Do not adopt this on a surface where an admin-panel filter outage blocks operational work.

Scaling Runtime cost is negligible — the filter compiles to a where clause, and pill rendering is a handful of DOM nodes. The real scaling concern is inherited from Nova, not this package: a filter whose apply() hits an unindexed column will table-scan on large datasets, and a multi-select pill filter makes it easy for users to construct expensive queries casually. Index the filtered columns before exposing pills, precisely because pills lower the friction of using the filter.

Failure modes

• Silent no-op: if apply() returns the query unchanged on an unrecognized value, users see pills that appear selected but filter nothing. Verify behavior on malformed or stale filter state.
• Asset publish failure: the filter class loads but the pill component 404s, degrading to an empty or broken filter panel. Add a smoke check to the post-deploy verification for admin routes.
• Nova upgrade breakage: the component fails to mount after a Nova minor/major bump. This is the highest-probability failure and should be caught in staging, not production admin.
• Stale filter state in URLs: pill filters are commonly encoded into the index query string; a removed or renamed option can leave bookmarked URLs filtering on a value that no longer exists.
• Accessibility regression: users navigating by keyboard cannot operate the filter. Low severity for an internal tool, high severity if the admin panel is subject to an accessibility audit.

Ramp-up Minimal. A Laravel developer familiar with Nova can read the entire package in under an hour and extend the base filter in minutes. The onboarding burden is not the code — it is the institutional knowledge that this dependency is unmaintained and that we, not upstream, are responsible for it. Capture that in the ADR so it survives team turnover.