Filament Truss Laravel Package

Product Decisions This Supports

• Build vs. buy for diagramming inside an admin panel. This package is the "buy" answer for the narrow question: should we render Truss diagrams inside Filament, or build a panel page + asset pipeline ourselves? It is a thin integration layer over albertoarena/laravel-truss, so the real build-vs-buy trade-off is Truss vs. an alternative diagram library (Mermaid, D2, Excalidraw, a hosted service) — this package only removes the Filament wiring cost, which is small but non-zero.
• Where diagrams live in the product. It commits you to diagrams as an in-panel surface (Filament resources/pages with a sidebar) rather than a public-facing page or docs site. That is a positioning decision, not just a technical one: it suits internal tooling, ops/runbook views, architecture notes for the team, and admin-only ERD/flow views. It is a poor fit if the diagram is a customer-facing artifact.
• Roadmap sequencing of vendor updates. v1.0.1 is a pure dependency-floor bump (laravel-truss 1.13.1+) with no markup, style, or script changes. The only roadmap-relevant read is that the package tracks upstream closely and will periodically require a coordinated composer update of a transitive dependency to pick up rendering fixes. Budget a small recurring maintenance line, not a one-off integration cost.
• Version-pinning and platform-baseline decisions. The stated requirements — PHP 8.2+, Laravel 12+, Filament 5 — put this on a modern-only baseline. Adopting it is effectively a vote to keep the admin panel on the current Laravel/Filament major line; it should not be planned into a product that is intentionally holding on Filament 3/4 or Laravel 10/11.
• Evidence for a "thin wrapper" architecture preference. The failure mode described in v1.0.1 (toolbar sizing measured the window instead of the bar, so a 1280px window with a sidebar left the toolbar ~810px and the responsive steps never fired) is exactly the class of bug that a wrapper package cannot fix locally — the fix landed upstream and this release just raised the floor. Useful precedent when deciding whether to depend on thin wrappers at all: they inherit upstream bugs and upstream latency.
• Not supported by this release: any decision about diagram feature scope (node types, layouts, export, interactivity). v1.0.1 adds no capability; it fixes one layout defect in one control.

When to Consider This Package

Consider it when all of the following hold:

• You are on Filament 5 / Laravel 12 / PHP 8.2+ already, or are migrating to them. This is a hard gate, not a preference — nothing here backports to older Filament.
• Your diagram need is internal and admin-facing — architecture sketches, ERDs, runbooks, flowcharts rendered inside a panel page where a sidebar is present.
• You have already chosen Truss as the diagram syntax/renderer, or are neutral between Truss and alternatives. If you have no opinion on the renderer, evaluate Truss on its own merits first; this package is not the deciding factor.
• You want the integration done for you rather than maintaining a custom Filament page that loads Truss assets and passes source text through. The saving is real but modest.
• You can absorb coupled dependency upgrades. Note the specific behavior in v1.0.1: the fix ships upstream, and this package only moves the constraint. If your lockfile already resolves laravel-truss 1.13.1, you already have the fix without touching this package — worth knowing before you schedule an upgrade ticket.

Look elsewhere when:

• The diagram is customer-facing, needs embedding outside Filament, or must be exported (SVG/PNG/PDF) as a first-class workflow. Reach for the renderer directly, or a different tool.
• You are on Filament 3/4 or Laravel ≤11. This package will not install, and there is no indication of a compatibility branch.
• You need guaranteed long-term support, a release cadence commitment, or vendor indemnity. This reads as a single-maintainer integration package with a 1.0.x line; treat it accordingly.
• Your diagram needs are trivial (one static image, one Mermaid block). A Blade partial and a CDN script tag is less surface area than a dependency chain.
• You need responsive/collapsible panel layouts with unusual toolbar configurations. The v1.0.1 bug was precisely a width-measurement assumption about the containing bar; it is fixed for the sidebar case, but the class of bug (layout measured against the wrong container) is the kind of thing that recurs in embedded UI. Verify against your actual panel layout before committing.

Adoption note on this release specifically: v1.0.1 contains no breaking changes, no deprecations, and no new features. It raises the laravel-truss floor to 1.13.1 to carry an upstream toolbar-sizing fix. It does not change an adopt/hold recommendation on its own — it slightly improves the reliability signal (maintainer is tracking upstream and shipping the constraint bump promptly rather than vendoring a patch).

How to Pitch It (Stakeholders)

For executives (one paragraph): We are evaluating a small add-on that lets our admin panel display architecture and process diagrams directly, instead of us building and maintaining that view ourselves. It is a thin layer over an existing open-source diagram renderer, so the cost is low and the risk is concentrated in the fact that it depends on a modern platform baseline and on an upstream project we do not control. The latest release (v1.0.1) is a maintenance patch — it fixes a toolbar layout glitch that appeared in narrow panel widths by pulling in a newer version of the underlying renderer. It adds no features and changes nothing we would build against, so it should not move our timeline; it does confirm the maintainer is actively keeping the integration current.

For engineering:

• Scope: an integration package, not a renderer. It wires albertoarena/laravel-truss into Filament 5. Bug surface is therefore split — rendering defects are upstream, wiring defects are here.
• v1.0.1 is a constraint bump only: requires laravel-truss 1.13.1+. No changes to this package's markup, styles, or scripts. Upstream fix: the toolbar sized its responsive breakpoints from window instead of the toolbar's own width; with a panel sidebar, a 1280px viewport yields an ~810px toolbar, so no breakpoint fired and the Filter field absorbed the entire shortfall as an empty square. Now measured against the bar.
• Upgrade action: composer update albertoarena/filament-truss albertoarena/laravel-truss. If your lock already holds laravel-truss 1.13.1, you have the fix regardless — check before opening a PR.
• Hard requirements to verify in CI: PHP 8.2+, Laravel 12+, Filament 5. No downgrade path is offered.
• Verification: check the diagram toolbar at a realistic panel width with the sidebar expanded — that is the exact configuration the regression appeared in. A passing test at full window width would not have caught it, and will not catch the next one.
• Ongoing cost: expect periodic coordinated upgrades when upstream ships fixes. Budget it as routine dependency hygiene, not as project work.
• Open question worth resolving before adoption: whether we standardise on Truss at all. If we would pick a different renderer, this package's value drops to roughly the effort of one Filament page.