Filament Widget Tabs Laravel Package

Getting Started

• Install and publish. Add the package via Composer, then run the publish command to emit its config (and any theme/CSS assets). Check config/ for the default theme mappings and the list of supported theme names.
• Look here first. The Theme enum (or equivalent) shipped in the package is the source of truth for available themes (Success, Danger, Info, Warning, Secondary). Read the enum cases and the trait/class that exposes ->success(), ->theme(), ->gradient(), and ->customThemeClasses() before writing markup.
• First use case. Apply a pre-built theme to a UI element and confirm the styling renders:

// Shorthand — uses the built-in Success (green) theme
$component->success();

// Generic form — pass the enum
$component->theme(Theme::Danger);

// Add a gradient on top of the chosen theme
$component->theme(Theme::Info)->gradient();

• Sanity check. Render one example of each of the five themes plus one gradient variant in a scratch view. If the colors don't appear, the CSS classes are almost certainly missing from your compiled Tailwind/CSS bundle (see Gotchas).

Implementation Patterns

• Prefer shorthand for the common five. ->success(), ->danger(), ->info(), ->warning(), ->secondary() are the least error-prone path. Reach for ->theme(Theme::X) when the theme is being passed around as a variable or stored in config.
• Drive themes from data with enums. Since ->theme() accepts the enum, cast model/status columns to the enum rather than juggling raw strings. This keeps validation at the boundary and makes invalid themes a type error instead of a silent styling no-op.
• Gradients as an additive layer. Treat ->gradient() as a modifier applied after the base theme, not a replacement for it. Compose theme + gradient consistently across your app so a "success" element always reads as the same green whether or not it has a gradient.
• Use ->customThemeClasses() for brand tokens. Map your design-system classes (e.g. brand primary, hover states) onto the package's theme slot rather than editing vendor CSS. Keep these mappings in one place — a config file or a dedicated theme provider — so restyling is a single edit.
• Closures for conditional theming. Use a closure where the theme depends on runtime state (user role, severity, feature flags). Keep the closure pure and cheap; it will be evaluated per render, so avoid queries or heavy logic inside it.
• Compose in a wrapper. If themes are used on many elements, wrap the package in a small app-level helper (e.g. statusTheme($status)) that returns the configured/flavored theme. Consumers then call one method instead of repeating enum logic.

Gotchas and Tips

• Tailwind purge / safelist. The most likely failure: theme classes are generated dynamically, so JIT scanners can't see them in your templates and they get purged. Add the package's theme classes (including gradient variants) to safelist in tailwind.config.js, or include the package's source path in content.
• Class conflicts and specificity. ->customThemeClasses() and ->gradient() both emit classes onto the same element. CSS ordering, not call order, decides the winner. If a custom class isn't taking effect, inspect the rendered class attribute and check for conflicting utilities rather than assuming the method was ignored.
• Gradient + theme interplay. Confirm whether ->gradient() is intended to override background colors or layer on top. Test with each of the five themes — a gradient tuned for Success may look wrong on Secondary.
• Enum drift. New themes can be added in minor releases. If you branch on Theme cases anywhere (e.g. a match), add a default arm so an unexpected case doesn't throw after a package upgrade.
• Closure evaluation cost. Dynamic theme closures run on every render. If the logic is expensive, memoise the resolved theme in a view model or computed property instead of recomputing in the closure.
• Debugging tip. Dump the resolved class string (inspect the rendered HTML or dd() inside your wrapper helper) before chasing config — most theming issues are "class not in the bundle" or "two utilities fighting", not a package bug.
• Extension points to favor. This release leans on custom classes and closures rather than forking. Exhaust those before overriding vendor views — it keeps upgrades (like this one) painless.