Filament Collapsible Subnav Laravel Package

Product Decisions This Supports

Build vs. buy for admin UX polish. This is a ~zero-cost, MIT-licensed, drop-in improvement to the internal admin panel that would otherwise be a half-day-to-two-day front-end task (toggle, cookie persistence, FOUC prevention, SPA re-sync, per-major selector fixes). Default decision should lean "buy," with the caveat that it's a one-maintainer package — treat it as vendored code you'll own if it breaks, not a strategic platform dependency.

Feature decision: sub-navigation density on resource pages. If your Filament resources carry 6+ tabs or relation managers with SubNavigationPosition::Start, the sub-nav column is stealing horizontal content width from the actual work surface (tables, forms, detail views). This package is the cheapest lever to reclaim that width without an IA redesign.

Diagnostic input to roadmap. The collapsed-state cookie is a free usage signal. If most users collapse the sub-nav and never expand it, the finding isn't "nice toggle" — it's "our tab structure is overloaded." That data should feed a roadmap item to consolidate tabs, promote the top 2–3 tabs, or replace the tab set with in-page sections/search. Run it as a time-boxed two-week trial on one high-traffic resource page, baseline the page's core task (time-to-complete, tab click-through), and re-measure.

Scoping/prioritization: what not to build. Explicitly deprioritize hand-rolled collapse JS. The non-trivial 10% — cookie state server-rendered into <head> to avoid flash, plus re-applying state on livewire:navigated for SPA panels — is exactly where internal implementations quietly break. Buying that logic (free) is better value than owning it.

Rollout control as a natural feature flag. Because the plugin only renders on pages using SubNavigationPosition::Start, "which pages get the collapsible sub-nav" is a per-resource code decision, not a global switch. That gives you a reviewable, incremental rollout with no extra config surface and no "do we enable the plugin?" debate.

Use cases worth flagging as candidates: admin backoffices sold to clients with many-tab resource pages; panels running ->spa() (strongest technical justification); 1280–1440px laptop-heavy user bases where an expanded sub-nav costs real content width; white-label SaaS backoffices where perceived polish matters in demos.

When to Consider This Package

Take it if all of the following hold:

• You're on Filament v3, v4, or v5 and already use (or are willing to use) SubNavigationPosition::Start on at least a handful of resource pages.
• Horizontal space on those pages is a real complaint — dense tabs eating the content column.
• Your panel uses ->spa(), or you care about no-flash-on-reload behavior.
• You can accept a single-maintainer, ~10-star, zero-dependent dependency, with an explicit version pin (^1.6) and a named internal owner.
• You can add one CI smoke check: toggle exists → clicking adds the collapsed class → reload keeps it collapsed.

Look elsewhere (or build/buy differently) if:

• You need main panel sidebar collapse. This package deliberately does not touch the primary navigation; it's sub-nav only. Wrong tool.
• Your sub-navigation is Top or End. Nothing renders. No harm, no value.
• You have deep theme customization on tooltips. v3 uses Tippy, v4/v5 fall back to a CSS ::after tooltip and native title — collapsed-state tooltips may look inconsistent with your branded UI.
• Strict dependency governance. One maintainer, minimal adoption, no security posture to point at. If your policy forbids micro-dependencies for UI, vendor the ~two files that matter (the <head> injection and the livewire:navigated listener) and own them.
• Heavy CSP / inline-style restrictions and you won't run the optional collapsible-subnav:install + npm run build theme integration. Solvable, but it's work you should budget.
• You're on an old Filament major or a PHP/Laravel combination outside 8.1+ / 10–13. Compatibility matrix doesn't cover you.

Recurring cost to accept: selector brittleness across Filament majors. Filament v4 renamed .fi-sidebar-item-button → .fi-sidebar-item-btn and tooltips silently stopped attaching with no error — that's why v1.6.0 exists. Budget a visual check on every Filament upgrade (collapsed icons, tooltip on hover, hidden badges, padding) as recurring maintenance, not one-time integration.

How to Pitch It (Stakeholders)

For executives (one paragraph): "A free, MIT-licensed UI plugin for our admin panel that lets users collapse the secondary tab sidebar on busy record pages, reclaiming horizontal space for actual work. It's a small, low-risk polish item — no license cost, a one-line install, and it ships with sensible defaults. The main caveat is that it's maintained by a small vendor, so we pin the version and own the fallback. We'll trial it on one high-traffic page for two weeks; the real payoff is that it also tells us whether our tab layout is overloaded and worth redesigning."

For engineering (the practical brief):

• Scope: sub-navigation sidebars only, on pages using SubNavigationPosition::Start. Does not touch the main panel nav.
• Install: composer require emuniq/filament-collapsible-subnav, clear caches. No publish step, no config file. Optionally run php artisan collapsible-subnav:install + npm run build to move the CSS into the theme and drop an inline block per response.
• Prefer explicit registration over auto-registration — add ->plugin(CollapsibleSubnavPlugin::make()) per panel so the change is visible in code review rather than silently applied to every panel by composer require.
• If we use ->spa(): do not remove the livewire:navigated re-sync listener. It's the bulk of the non-trivial logic and the likeliest thing to break silently.
• Pin ^1.6, name an owner, and vendor-fork option if the maintainer goes quiet.
• One smoke check in CI (toggle present, collapsed class applies, reload persists). That check is the guard against the realistic failure mode — a silent visual regression after a Filament bump.
• Validate the no-flash behavior in production behind our actual CDN: Cloudflare Rocket Loader can strip the early script; the plugin uses data-cfasync="false" to survive it, but HTML minifiers and some edge workers drop unknown attributes. Test the real stack, not php artisan serve.