Palette Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require awcodes/palette
   

   Ensure your Filament version matches the package compatibility table (e.g., 3.x for Filament 5.x).

2. Theme Integration: Add the package’s Blade views to your custom theme’s CSS file:

   @source '../../../../vendor/awcodes/palette/resources/**/*.blade.php';
   

   Note: Required for standalone Filament or if not using a custom theme.

3. First Use Case: Register the field in a Filament form:

   use Awcodes\Palette\Fields\PaletteField;
   
   PaletteField::make('color')
       ->presets(['#FF5733', '#33FF57', '#3357FF']) // Default presets
       ->default('#FFFFFF'); // Optional default
   

Implementation Patterns

Common Workflows

1. Dynamic Presets: Fetch presets from a database or API:

   PaletteField::make('accent_color')
       ->presets(fn () => $this->getCustomPaletteColors())
       ->livewire(); // For real-time updates
   

2. Theming Integration: Extend Filament’s theme with palette-specific styles:

   /* app/filament/resources/css/filament.css */
   .palette-field .palette-swatch {
       border-radius: 4px;
       box-shadow: 0 2px 4px rgba(0,0,0,0.1);
   }
   

3. Validation & Rules: Combine with Filament’s validation:

   PaletteField::make('primary_color')
       ->presets(['#1DA1F2', '#170939'])
       ->rules(['required', 'hex_color']);
   

4. Panel-Specific Configuration: Override presets per panel:

   // In a custom Filament panel
   PaletteField::make('theme_color')
       ->presets(['#000000', '#FFFFFF', '#FF4500']);
   

Integration Tips

• Localization: Use Filament’s localization for preset labels:

  PaletteField::make('brand_color')
      ->presets([
          '#FF0000' => __('Red'),
          '#00FF00' => __('Green'),
      ]);
  

• Accessibility: Ensure contrast ratios for presets (e.g., dark/light pairs).
• Performance: Lazy-load presets for large palettes:

  PaletteField::make('custom_palette')
      ->presets(fn () => $this->loadPaletteFromCache());
  

Gotchas and Tips

Pitfalls

1. Theme Dependency:

   • Issue: Missing @source in CSS causes blank fields.
   • Fix: Verify the path in resources/css/filament.css or your custom theme file.

2. Preset Overrides:

   • Issue: Dynamic presets not updating due to caching.
   • Fix: Use ->livewire() or clear Filament’s cache:

     php artisan filament:cache-clear
     

3. Hex Validation:

   • Issue: Custom validation fails for shorthand hex (e.g., #F00).
   • Fix: Extend the field’s validation rules:

     use Awcodes\Palette\Fields\PaletteField;
     PaletteField::make('hex_color')
         ->rules(['hex_color', 'size:7']); // Enforce full #RRGGBB
     

4. Filament Version Mismatch:

   • Issue: Package throws ClassNotFound errors.
   • Fix: Check the compatibility table and update Filament or the package.

Debugging

• Inspect Blade Output: Dump the rendered field to debug:

  dd($this->form->getField('palette_field')->getView());
  

• Console Logs: Enable Filament’s debug mode:

  // config/filament.php
  'debug' => env('FILAMENT_DEBUG', false),
  

Extension Points

1. Custom Swatch Rendering: Override the swatch template:

   <!-- resources/views/vendor/filament/forms/components/field.blade.php -->
   @if($field instanceof \Awcodes\Palette\Fields\PaletteField)
       <div class="custom-swatch">{{ $field->getColorPreview($state) }}</div>
   @endif
   

2. Preset Management: Add a palette editor panel:

   use Awcodes\Palette\Resources\PaletteResource;
   
   PaletteResource::make()
       ->columns(['name', 'colors'])
       ->pages([]);
   

3. Dark Mode Support: Dynamically adjust swatch styles:

   @media (prefers-color-scheme: dark) {
       .palette-field .palette-swatch {
           filter: brightness(0.9);
       }
   }
   

4. API Integration: Sync presets with an external service:

   PaletteField::make('api_color')
       ->presets(fn () => $this->fetchFromApi('/palettes'))
       ->afterStateUpdated(fn ($state) => $this->syncToApi($state));