Nova Inline Badge Field Laravel Package

Getting Started

Start with the package README's options reference and the shipped Blade component/view — those two files tell you everything about how textColor and badgeColor are resolved and rendered. In a Laravel app the typical setup is:

1. Require the package and let package discovery register the service provider.
2. Publish config/assets if the README instructs it (php artisan vendor:publish --tag=...).
3. Render the component once in a scratch route or Blade view with no options, then again with badgeColor and textColor set, to confirm defaults and override behaviour.

The first real use case is almost always status chips in a table or detail view — e.g. "Paid", "Pending", "Failed" — where the colour conveys meaning. Wire one status through the component before touching the rest of the UI; colour options are the part of this package most likely to interact with your design system, so validate the visual result early.

Implementation Patterns

Centralise colour mapping, don't inline it. Hard-coding badgeColor="green" across dozens of views is the main source of drift. Put the mapping in one place — an enum, a config array, or a small presenter/model accessor — and have views ask for a badge by domain value:

// e.g. app/Support/StatusBadge.php
public static function for(string $status): array
{
    return match ($status) {
        'paid'    => ['badgeColor' => 'green',  'textColor' => 'white'],
        'pending' => ['badgeColor' => 'yellow', 'textColor' => 'black'],
        'failed'  => ['badgeColor' => 'red',    'textColor' => 'white'],
        default   => ['badgeColor' => 'gray',   'textColor' => 'black'],
    };
}

Then bind the array into the component. This keeps the new options useful without letting them leak into every template.

Treat textColor as a paired concern of badgeColor. The natural workflow is: pick the background from your palette, then pick a foreground that passes contrast. Encode both together in the mapping above rather than letting callers set one and forget the other.

Wrap, don't scatter. If the package renders a generic badge, add a thin app-level component (e.g. <x-status-badge :status="$invoice->status" />) that owns the mapping and delegates to the package. Consumers stay declarative, and if the package's option names or accepted values change, you edit one file.

Consistency across contexts. Use the same mapping for table rows, detail headers, filters, and notification payloads so a "Failed" chip looks identical everywhere. If the package is also used outside Blade (JSON payloads, mail templates), keep the colour tokens as data and render them at the edge.

Test the mapping, not the package. Feature-test that a given domain status yields the expected option array or rendered class string. That catches regressions when you extend the palette and pins the 1.0.3 additions in place.

Gotchas and Tips

• Accepted value types are the big unknown. Verify whether badgeColor/textColor expect Tailwind utility names (green, red), raw CSS (#16a34a), or semantic tokens (success, danger). Passing a hex string where a class name is expected (or vice versa) typically fails silently — the badge renders unstyled rather than erroring.
• Class purging. If colours resolve to Tailwind classes, dynamically constructed class names (e.g. "bg-{$color}-500") will be stripped by the build unless the full class names appear literally in your source or the package ships a safelist. Prefer the package's own value set over string concatenation.
• Contrast is your job. textColor is a foot-gun: it happily lets you put white on yellow. Add a quick manual pass (or a contrast check in your mapping test) over the combinations you actually use.
• Config caching. After publishing or editing a package config file, run php artisan config:clear; stale cached config is the usual cause of "my colour option is ignored".
• Check for escaping in textColor usage. If the colour value ends up in a style attribute or an inline class, confirm the component escapes it; never pass user-supplied strings into colour options.
• Extension points to look for: published config for default colours, a resolvable colour map, or overridable views. If the package exposes a view you can publish, overriding it is safer than subclassing, but it will diverge on upgrades — note it and re-check on each release.
• Upgrade note for 1.0.3: the release is additive (new textColor and badgeColor options), so there is no migration work. Because these options are new, existing badges keep their previous appearance — adopt them deliberately via your central mapping rather than assuming global defaults changed.