Resource Navigation Tab Laravel Package

Getting Started

Resolve the framework mismatch before you run composer require. The package description says it "adds tabbed navigation to Laravel Nova resource sidebars," but the repository, composer.json, and the release notes for 2.1.5 (which reference a HasOne field failing on initial page load) all describe a Filament plugin that groups form fields into tabs. Those are two different products with two different integration surfaces. Open composer.json on GitHub and confirm the framework constraint and the plugin entry point in src/ before you type a command. If your panel is Nova and this is a Filament plugin, the evaluation ends there — no amount of glue code makes that worth it for a presentation-layer feature.

Pin >=2.1.5, not ^2.1.0. The latest tag is v2.1.5 (14 Nov 2023), and its single change is a genuine defect fix: a HasOne field that rendered blank on initial page load. Anything on 2.1.0–2.1.4 ships that blank relationship field, which is a data-entry hazard inside a form that looks fine until an operator saves without noticing. Do not accept a floating 2.x.

composer require digital-creative/resource-navigation-tab:^2.1.5

Then verify the published asset (if the package ships one) matches the tag — the 2.1.5 fix is JavaScript-side, so a stale published bundle from an earlier install will reproduce the exact bug you upgraded to avoid.

Read src/ in this order, because the README lags the code:

1. The service provider / plugin class — how it hooks into a panel (->plugin(ResourceNavigationTabPlugin::make()) in your PanelProvider, or a trait, or a fluent form-schema method — confirm which).
2. The trait or base class — how tabs are declared and how field groups map to tab labels.
3. resources/js and resources/views — whether the HasOne fix lives in source you compile or a prebuilt bundle you must republish.

Step 3 is the one that gets skipped and regretted.

First use case: exactly one resource, chosen deliberately. Pick something with 10+ fields, at least one HasOne, and at least one BelongsTo — then group it as Basics / Relations / Meta. This exercises the patched code path, gives you a real read on whether tabs help or just add clicks, and costs one file to revert.

Smoke-test on a cold load. The known defect was a mount-time bug. Hard-refresh the edit page, open it in a fresh browser tab, and navigate in from the index. Clicking through a warm page will not reproduce the class of failure you are guarding against.

Implementation Patterns

Group by operator mental model, not by field type. Basics / Pricing / Relations / SEO / Meta is a convention you can paste into internal docs and onboarding. Strings / Numbers / Dates is a filing cabinet nobody asked for. Decide the grouping once, write it into your team's admin conventions, then apply it uniformly — the convention is the actual deliverable even if you drop the package later.

Identity fields stay on the first tab, always. Name, status, tenant, and anything an operator scans to answer "which record am I looking at" belongs on the landing tab. Tabs hide fields; they must never hide which record is open.

Isolate relationship fields into a dedicated tab. HasOne / HasMany / BelongsTo is the least-tested path in this package — the one known bug came from a user report, not CI. A dedicated Relations tab makes breakage visible in code review and trivially diagnosable in production.

Standardize the declaration snippet. Whether tabs are declared via a trait method, a fluent builder, or an array on the resource class, paste a canonical five-line example into your internal docs. That snippet is what prevents a dozen resources drifting into a dozen tab schemes six months from now.

One resource per PR. This is a presentational change; there is no reason to couple two resources' risk. Phased rollout also lets you codify the convention from the first resource before the second inherits a mistake.

Treat it as a presentation boundary — no domain logic smuggled in. No migrations, no schema changes, no API surface. If a tab refactor is blocking a deploy, a UI nicety has become load-bearing; split it out.

Compare against native Filament Tabs before committing. Filament ships form tab/panel primitives. If those already give you the grouping you want, this package is a dependency for zero marginal value. Run that comparison in hour one — it can end the evaluation early. If you do keep it, check in src/ whether the plugin composes with native Tabs (so you can nest columnar layouts inside a plugin tab) or only handles flat top-level grouping.

Time-box a fallback. Pre-agree that if the pilot fails, you spend one day writing a thin wrapper over native Tabs and move on. Deciding that in advance prevents a stalled evaluation from lingering in a sprint.

Gotchas and Tips

v2.1.5 is a floor, not a feature. Inheriting a project on 2.1.4 or earlier? The upgrade is a straight patch — no migration, no config changes. Do it before you evaluate anything else, or you will spend an afternoon debugging a phantom blank relationship field.

Verify the JavaScript fix actually ships. The 2.1.5 change is front-end. On a fresh clone, confirm the asset build/publish step reproduces the patched bundle, and confirm you aren't serving a stale published asset left over from a previous install. Diff the compiled asset or check a version string against the tag.

Validation errors inside inactive tabs — test this explicitly, it's the highest-value check. Filament validates all fields, not just visible ones. Submit a form with a required field left blank in a hidden tab and watch what happens. If the UI auto-switches to the offending tab with the error visible, you're fine. If it produces a generic failure with no pointer, that is a UX failure you cannot ship — and it may not be patchable from outside the package.

Reactive and conditional fields across tab boundaries. A field hidden via visible() or driven by reactive(), whose dependent field lives in a different tab, must evaluate correctly whether or not its tab is mounted. Test it directly; do not assume.

Field-type coverage is uneven and unvalidated. One known bug, caught by a user report. The package's matrix across relationship, upload, and KeyValue fields is thin. Any field type you place inside a tab is unverified until you verify it. Keep a short checklist of field types your resources actually use and walk it once per Filament minor upgrade.

Single maintainer, zero dependents, long silence broken by one community PR. Read that as alive, not staffed. Budget 1–2 hours per quarter for release review and re-testing after Filament upgrades, and pre-agree the MIT fork contingency now rather than during an incident.

Filament major bumps are the real exposure. A single-maintainer presentation plugin is the likeliest casualty of a major framework upgrade, and it fails at render time in the admin panel — typically the morning after a dependency update. Add a runbook line: "re-test all tabbed resources after Filament major bumps."

Don't tab short forms. Below roughly 8–10 fields, tabs add clicks and hide context for no gain. This is an improvement for dense resources and an active regression for sparse ones.

Debugging sequence that actually works:

1. Confirm the pinned version in composer.lock.
2. Confirm the published asset matches that version.
3. Check the browser console for JS errors on first load specifically.
4. Reduce to one tab containing one HasOne field to isolate.
5. Fall back to native Tabs on that resource while you read src/.

With thin documentation, steps 4–5 are almost always faster than chasing an issue thread.