Shout Laravel Package

Product Decisions This Supports

Feature-level: contextual guidance where users actually are. Shout is a presentational Filament schema component, not a field that stores state. That makes it a low-cost lever for the small, high-friction moments in an admin workflow: explaining why a field is disabled, warning that changing a setting has downstream consequences, telling an admin what to do next after a state transition, or confirming which tenant/environment they're editing. These are usually the requests that arrive as "users keep asking support how to…" — and the cheapest fix is inline copy, not new screens.

Build vs buy: buy, decisively. The honest build estimate is "an hour to prototype, a day to make it consistent." Filament already has Placeholder and notification primitives, but neither gives you a styled, color-coded, icon-bearing block with inline Action buttons inside the schema in a single fluent API. Shout is ~one Blade view and a thin PHP class, MIT-licensed, and versioned 1.x–4.x against Filament 2.x–5.x, with a 4.x line that covers Filament 4 and 5 on one branch. Building our own version means owning dark-mode contrast, RTL, icon aliases, and action alignment — all of which the maintainer has already iterated on (v4.1.1 fixed dark-mode palettes, icon alias resolution, and inline action alignment). That is real, unglamorous maintenance we would otherwise absorb.

Use cases worth roadmapping. (1) Onboarding and empty states — first-run guidance in create/edit forms. (2) Risk and compliance copy — a danger-colored notice with a link to policy next to a destructive toggle. (3) Upsell and plan gating — warning notice plus an Action pointing at the upgrade flow, rendered only when the tenant's plan lacks a feature, driven by a closure. (4) Operational awareness — infolist entries showing what a record's status means and what the next permitted action is. (5) Migration and deprecation comms — a dismissable-in-spirit notice during a data-model change.

Roadmap framing. Treat this as design-system surface area, not a product bet. It does not unlock new capabilities, does not touch the domain model, and adds no migrations, routes, or container bindings. The PM-level decision is therefore small: adopt it as the sanctioned pattern for inline notices so we don't accumulate three bespoke implementations, and write a one-line guideline ("use Shout for contextual notices; use notifications for transient feedback") so the pattern stays consistent.

When to Consider This Package

Adopt when all of the following hold:

• You are on Filament 4.x or 5.x (use the 4.x release line) or Filament 3.x (3.x) / 2.x (1.x) — check the compatibility table before pinning.
• Your need is in-panel, in-context guidance inside a form or infolist schema(), adjacent to the field it explains.
• You are willing to run a custom Filament theme. This is the real adoption cost: installation requires a custom theme and adding the package views to your CSS via @source '../../../../vendor/awcodes/shout/resources/**/*.blade.php'. Teams without a custom theme must set one up first, which is a bigger lift than composer require.
• You want the notice to carry a call to action — actions() accepts genuine Filament Action objects, so links to docs, upgrade flows, or related records work without custom markup.

Look elsewhere when:

• You need persistence or validation. Shout is a fancy placeholder; it has no state, no rules, no submission semantics. For a required acknowledgement ("I have read the policy") you need a real Checkbox/Toggle field.
• You need transient feedback after an operation — use Filament notifications, which are built for that and don't require layout real estate.
• You need this outside Filament — public pages, emails, API responses, or non-Filament Blade views. It cannot serve those.
• You need dismissible, remembered notices. No dismiss/persistence API exists; hiding is at most conditional rendering via closures.
• Dependency-risk tolerance is low. 71 stars, zero dependents, effectively a single-maintainer package on a fast-moving Filament release cadence. The blast radius if it stalls is small (delete the component, replace with Placeholder plus a custom view), but a strict "no single-maintainer UI deps" policy would exclude it. Note also that v4.1.1 requires awcodes/focus, pulling in a second package from the same author for documentation tooling.
• You need something heavier — rich text callouts, multi-step guidance, or conditional branching logic. That's a feature, not a component.

How to Pitch It (Stakeholders)

To executives — in one paragraph: Shout is a small, free (MIT), open-source UI component that lets us put clear, styled notices directly inside our admin forms — the "heads up, this changes your billing" or "here's what to do next" messages. It replaces ad-hoc copy and one-off screens with a consistent, accessible pattern, and it's the kind of improvement that measurably reduces support tickets and onboarding confusion. Cost is negligible: no licensing, no infrastructure, no new services, roughly a day of engineering to adopt and standardize. Risk is contained by design — it's presentation-only, touches no data, and can be removed in an afternoon if we ever want to.

To engineering — the substance:

• What it is: a Filament schema component (Awcodes\Shout\Components\Shout) that renders an inline contextual notice. Pure presentation — no migrations, routes, service bindings, queues, or events. Composition via content(), heading(), icon(), iconSize(), icon(false), color() (Filament Color object or hex), and actions() accepting real Filament\Actions\Action instances.
• Integration: drop it into any schema() array on a form or infolist. Requires a custom theme and an @source directive pointing at the vendor Blade views — budget for that, especially in panels that currently use the default theme. Version-pin against your Filament major; 4.x supports Filament 4 and 5 simultaneously, which eases upgrades.
• Quality signals: the recent v4.1.1 release is a maintenance-quality tell — it fixed dark-mode contrast (a genuine accessibility win), made registered icon aliases resolve, removed empty heading markup, and corrected icon(false) indentation and inline action alignment. Tests and CI exist; docs are maintained on a dedicated docs site. RTL was addressed as far back as 1.0.1.
• Standards to adopt alongside it: one guideline for when to use Shout versus notifications, and a rule that notice copy is treated as product copy (reviewed, not lorem-ipsum) since it will be the first thing users read at decision points.
• Risk and exit: single maintainer, modest adoption, aggressive upstream Filament cadence. Mitigation is trivial — usage is declarative and confined to schema() methods, so replacement with a custom view is a contained, mechanical change. Recommend pinning to a known-good minor and reviewing at each Filament upgrade rather than floating the constraint.