Filament Chart Palette Laravel Package

Getting Started

• Install with composer require jccoca/filament-chart-palette. No publish/config step is mentioned in the release notes, so there is nothing to publish before first use.
• Look first at the package README.md (linked from the release) for the full palette API, supported chart types, and shade syntax. The release notes only show the happy path.
• Minimum integration is two steps: use HasChartPalette; inside your ChartWidget, then call $this->getChartPalette($this->getType()) inside getData() and feed the result into a dataset color key (typically backgroundColor).
• First use case: a pie/doughnut chart where you want N distinct, theme-consistent colors without hand-picking hex values per slice. Return the palette directly as backgroundColor and Chart.js will distribute one color per slice.
• Because the palette is built on Filament's Color::class and Tailwind v4 OKLCH values, your first sanity check should be that the rendered colors visually match the rest of your Filament panel theme (light and dark).

Implementation Patterns

• Trait on the widget, palette in getData(). Keep the trait on the ChartWidget subclass and resolve the palette at data-build time. This keeps color logic co-located with the dataset it colors.
• Let getType() drive ordering. Pass $this->getType() so the package can order colors appropriately per chart type (adjacent-slice contrast for pie/doughnut vs. series contrast for bar/line). Avoid hardcoding 'pie' if the widget type can change.
• Multi-dataset series charts. For bar/line/radar with several datasets, call the palette once and index into it per dataset ($palette[0], $palette[1], …) rather than passing the full array to every dataset, otherwise all series share the same color ramp.
• Single-color datasets. For line charts you usually want one color per dataset, not an array. Use an indexed palette entry for borderColor and a low-alpha variant for backgroundColor (fill).
• Shade selection. When the release's "specific color shades" feature is used, standardize on a shade (e.g. 500 for borders, 100/400 for fills) in a small private helper so every widget in the panel stays visually consistent.
• Centralize the call. Wrap the palette in a protected helper on a base chart widget (protected function palette(): array) so shade, type, and ordering choices are defined once and reused across all chart widgets.
• Theme alignment. Since palettes derive from Filament's Color::class, changing the panel's primary color should cascade into charts automatically — treat that as the intended workflow and avoid hardcoded hex fallbacks.
• Tailwind v4 projects. The OKLCH→RGBA conversion exists so Chart.js (which does not reliably accept oklch()) receives valid colors. Let the package convert; don't pre-convert in your own code.

Gotchas and Tips

• Chart.js color format. Chart.js generally wants rgba()/hex, not oklch(). If you bypass the package and hand Tailwind v4 OKLCH values straight to a dataset, colors will silently fail or render black — always route through getChartPalette().
• Array vs. string. Pie/doughnut expect an array of colors; line/bar usually expect one color per dataset. Passing a full palette to a line dataset is a common cause of "why is my line multicolored" or unexpected legends.
• Unknown/custom chart types. If getType() returns something outside the package's known set, ordering may fall back to a default. Verify slice contrast on less common types (polarArea, radar) rather than assuming.
• Dark mode contrast. Palettes built from Filament colors should adapt, but contrast on dark panels is worth eyeballing — especially mid-range shades used as backgroundColor behind labels.
• Version coupling. The package targets Filament v4 and v5 and Tailwind v4. If you are on Tailwind v3 or Filament v3, expect the OKLCH conversion and Color::class behavior to differ; pin jccoca/filament-chart-palette and filament/filament together in composer.json and retest on Filament minor upgrades, since v5 Color internals are the package's main dependency surface.
• Debugging. dd($this->getChartPalette($this->getType())) inside getData() is the fastest way to confirm ordering, count, and RGBA formatting before blaming Chart.js options.
• Palette length. If a chart has more data points than palette entries, colors will repeat (or be missing). Check count($palette) against your dataset size, especially for dynamic/query-driven charts.
• Performance. The palette is computed per render; for dashboards with many widgets, resolving it once per widget and reusing the array (rather than calling per dataset) avoids repeated conversion work.
• Extension points. The trait method is the seam: override getChartPalette() in your widget or base class to inject brand colors or custom ordering while keeping the rest of the package's conversion behavior. Prefer that over post-processing the returned array in every getData().
• Testing. Unit-test the widget's getData() and assert the palette shape (array of valid rgba(...) strings, correct count) so Filament/Tailwind upgrades that shift color values fail loudly in CI rather than visually in production.