Filament Record Nav Laravel Package

Product Decisions This Supports

Feature/roadmap investment: "review one record at a time" workflows. Many internal admin panels exist to let an operator step through a queue — moderation, catalog QA, support triage, invoice/claim review. This package adds prev/next traversal to any ViewRecord/EditRecord page, which is exactly the affordance those workflows need. It informs the decision of whether to invest in a full queue/"review mode" surface or ship the cheaper increment first: two actions in getHeaderActions(), no page class changes, no new UI to design.

Build vs. buy (buy, clearly). The scope is deliberately narrow — resolve an adjacent record, resolve a URL, disable at the boundaries, style it like a native Filament action. That is maybe a day of engineering plus permanent maintenance, versus a composer require and four lines per page. The decision this supports is "spend the sprint on the review workflow, not on chevron buttons."

Prioritisation: a low-effort, high-visibility polish item. It is a good candidate for a "delight/quality" slot in a sprint because cost is near-zero, blast radius is one page class at a time, and the demo (rnd.nben.com.np, GIF) makes the value legible to non-technical stakeholders without a spec.

Scoping clarity — this is a UI affordance, not a workflow engine. It does not give you per-user queues, saved filters, assignment, or "jump to next unreviewed." Ordering is driven by a single global order_column (default id) plus previous_direction/next_direction, or by hand-written query overrides via the optional WithRecordNavigation trait. Product should treat it as sequential browsing, not queue management, and decide accordingly whether a real queue feature stays on the roadmap.

Rollout/risk decisions it de-risks. Because adoption is per-page and reversible (delete two lines), it is safe to pilot on one or two resources, instrument, and expand — a useful pattern for getting UX changes past a change-averse stakeholder.

Support/onboarding decisions. New hires and occasional admin users lose the "back to list, find my place, click next row" loop. That is a defensible support-ticket and training-cost argument, though you should measure it rather than assume it.

When to Consider This Package

Adopt when:

• You are already on Filament 4.x/5.x with Laravel 10–13 and PHP 8.2+ (per the README requirements; note the badge row says Laravel 11/12/13 while the requirements list says ^10.0 | ^11.0 | ^12.0 | ^13.0 — confirm against composer.json before committing to a version matrix).
• You have at least one ViewRecord or EditRecord page where users genuinely traverse records one by one, and the natural order is a single, indexed column (id, created_at, sort_order).
• You want the smallest possible diff: no trait, no interface, no lifecycle hooks — just action classes extending Filament's native Action, so every fluent method (label, color, size, tooltip, keyBindings) still works.
• Query cost matters and you want the documented guarantee of one database query per action per render (closures share a resolved-record cache).
• You are comfortable pinning a version and owning an upgrade check on each Filament major.

Look elsewhere, or budget for override work, when:

• Navigation must respect the table's active filter or search. Defaults order across the whole table from config; scoping to "the 40 records currently on screen" requires the trait plus custom getPreviousRecord()/getNextRecord() per page — the zero-config benefit evaporates at scale.
• Multi-tenancy is in play. The override examples use $this->getRecord()->newQuery(), which is your code, not the package's — so verify explicitly that the fallback query is tenant-scoped and permission-consistent with the resource, and that a user cannot traverse into a record they cannot view. Treat this as a pre-adoption security review item, not an assumption.
• Ordering is non-trivial — multi-column, computed, ranked, or nullable timestamps. The README's own troubleshooting flags that duplicate created_at values mean records "will not find each other," i.e. silent gaps in the sequence.
• Tables are large and order_column is unindexed. One query per action per render is fine as a count, but a >'x' ORDER BY col LIMIT 1 scan on an unindexed column is not. Indexing is a prerequisite, not a nice-to-have.
• You are in a supply-chain-reviewed or long-horizon environment. Signals are thin: 16 stars, 0 dependents, a single maintainer, first release cycle in 2026. The README, changelog, and releases are present and the architecture is unusually well documented for a package this size — but this is a small, young dependency. If your policy requires community validation or a support contract, this fails that bar; forking (MIT) is the realistic fallback.
• You need richer navigation semantics — first/last jumps, jump-to-record, breadcrumb context, "next unreviewed," per-user ordering. None of that is here.

Verdict shape: a low-risk, low-cost convenience dependency for simple, single-column-ordered admin panels — not a platform decision, and not a substitute for a real review-queue feature.

How to Pitch It (Stakeholders)

To executives (one paragraph): Our admin panel is where staff do record-by-record review work, and right now every record costs them a trip back to the list to find their place. This MIT-licensed package adds Previous/Next buttons to those screens — the buttons grey out automatically at the first and last record — for a few lines of code per page. It is not an infrastructure change, it does not touch our data model, and we can pilot it on one screen and remove it just as easily if it does not help. The investment is roughly a day; the return is less clicking and faster throughput on the review work our team already does. The main caveats are that it is a small, single-maintainer open-source package, so we pin the version and own upgrade checks, and we verify it respects our tenant and permission rules before it goes live.

To engineering (short brief): composer require nben/filament-record-nav, then PreviousRecordAction::make() and NextRecordAction::make() in getHeaderActions() on the target page — no trait, no page class changes. Actions extend Filament's native Action, so all fluent modifiers work. Target page is per-action via ->navigateTo(NavigationPage::View|Edit) or NavigationPage::custom('route-key'), resolved through Resource::getUrl(). Ordering is global via the publishable filament-record-nav config (order_column, previous_direction, next_direction); anything else needs the optional WithRecordNavigation trait overriding getPreviousRecord()/getNextRecord()/getRecordNavigationUrl(), with an optional HasRecordNavigation interface purely for PHPStan/Psalm. Deliberately depends only on Filament's stable $livewire injection API and uses no internal lifecycle hooks — good upgrade posture, but confirm against Filament 5 before we depend on it.

Ask and acceptance criteria:

1. One-day spike on a single, non-tenant-scoped ViewRecord page; confirm behaviour on Filament 4.x and 5.x if we run both.
2. Verify tenant/permission scoping of the adjacent-record query — a user must not be able to navigate into a record the resource would hide.
3. Confirm order_column is indexed on every table we enable it for; skip tables with duplicate timestamps.
4. Instrument before/after: records reviewed per session, time-to-next-record, and back-to-list events, so the "it feels better" claim becomes a number we can act on.
5. Pin the version in composer.json and add it to the Filament-major upgrade checklist; treat the maintainer bus factor as an accepted risk with a documented fork path.