Fancy Flux Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require wishborn/fancy-flux
   php artisan vendor:publish --tag=fancy-flux-config
   

   Configure the prefix in config/fancy-flux.php or .env (e.g., FANCY_FLUX_PREFIX=fancy).

2. First Use Case: Carousel

   use Wishborn\FancyFlux\Components\Carousel;
   
   class MyComponent extends Component {
       public function render() {
           return view('livewire.my-component')->with([
               'carouselItems' => ['Item 1', 'Item 2', 'Item 3'],
           ]);
       }
   }
   

   In Blade:

   <x-fancy::carousel :items="$carouselItems" />
   

3. First Use Case: Color Picker

   use Wishborn\FancyFlux\Components\ColorPicker;
   
   class MyComponent extends Component {
       public $selectedColor = '#000000';
   
       public function render() {
           return view('livewire.my-component');
       }
   }
   

   In Blade:

   <x-fancy::color-picker wire:model="selectedColor" />
   

4. First Use Case: Emoji Select

   use Wishborn\FancyFlux\Components\EmojiSelect;
   
   class MyComponent extends Component {
       public $selectedEmoji = '';
   
       public function render() {
           return view('livewire.my-component');
       }
   }
   

   In Blade:

   <x-fancy::emoji-select wire:model="selectedEmoji" />
   

Implementation Patterns

Usage Patterns

1. Component Registration Use the use_flux_namespace config to auto-register components under the flux namespace (e.g., <x-flux.fancy::carousel>). Disable if conflicts arise.

2. Dynamic Data Binding All components support Livewire’s wire:model for two-way binding. Example:

   <x-fancy::color-picker wire:model="user.profile_color" />
   

3. Customization via Props Pass props to override defaults:

   <x-fancy::carousel
       :items="$items"
       :loop="true"
       :autoplay="5000"
       :per-page="3"
   />
   

4. Slot Support Use slots for custom content (e.g., carousel item templates):

   <x-fancy::carousel>
       <x-slot name="item">
           <div class="p-4 bg-white rounded-lg">
               {{ $item }}
           </div>
       </x-slot>
   </x-flux.fancy::carousel>
   

Workflows

1. Theming Override Tailwind/Flux styles via config/fancy-flux.php:

   'theme' => [
       'carousel' => [
           'container' => 'bg-gray-100',
           'item' => 'p-4',
       ],
   ],
   

   Or extend the package’s CSS in your assets.

2. Integration with Forms Use wire:model for form fields (e.g., emoji picker for comments):

   <x-fancy::emoji-select wire:model="comment.emoji" />
   

3. Lazy Loading Dynamically load components via Alpine.js or Livewire’s mount():

   public function mount() {
       $this->loadCarouselItems = false;
   }
   

   <div x-data="{ showCarousel: false }">
       <button @click="showCarousel = true">Load Carousel</button>
       <x-fancy::carousel
           x-show="showCarousel"
           :items="$carouselItems"
       />
   </div>
   

4. Server-Side Logic Pre-process data in Livewire methods:

   public function updateCarouselItems() {
       $this->carouselItems = Cache::remember('carousel_items', now()->addHours(1), function () {
           return Item::all()->pluck('name');
       });
   }
   

Integration Tips

1. Flux Compatibility Ensure your Flux version supports the package (check composer.json for flux dependency).

2. Asset Management Publish assets for customization:

   php artisan vendor:publish --tag=fancy-flux-assets
   

3. Testing Use Livewire’s testing utilities:

   $this->assertComponentRendered('fancy::carousel');
   $this->assertEmitted('carousel-item-selected', ['item' => 'Item 1']);
   

4. Localization Extend the package’s language files (resources/lang) for multi-language support.

Gotchas and Tips

Pitfalls

1. Namespace Conflicts

   • Issue: Components may clash with official Flux or other custom components.
   • Fix: Set a unique prefix in config (e.g., fancy_) and use <x-fancy_::carousel>.

2. Livewire Version Mismatch

   • Issue: Package may not support your Livewire version.
   • Fix: Check composer.json for livewire/livewire compatibility. Downgrade/upgrade as needed.

3. Asset Loading

   • Issue: Custom CSS/JS not loading.
   • Fix: Run npm run dev or npm run build after publishing assets.

4. Environment-Specific Config

   • Issue: Config changes not reflecting in production.
   • Fix: Use .env overrides (e.g., FANCY_FLUX_PREFIX=prod_fancy) and restart the server.

5. Performance with Large Datasets

   • Issue: Carousel/emoji picker lagging with many items.
   • Fix: Implement pagination or lazy-loading:

     <x-fancy::carousel :items="$chunkedItems[0]" />
     <button wire:click="loadMore">Load More</button>
     

Debugging

1. Component Not Found

   • Verify the config prefix and namespace usage (e.g., <x-fancy::carousel> vs <x-flux.fancy::carousel>).
   • Check if the component is registered in app/Providers/AppServiceProvider.php:

     public function boot() {
         Flux::registerComponents([
             \Wishborn\FancyFlux\Components\Carousel::class,
         ]);
     }
     

2. Styling Issues

   • Inspect the published CSS (public/vendor/fancy-flux/css/fancy-flux.css) for overrides.
   • Use browser dev tools to check for specificity conflicts.

3. Livewire Events Not Firing

   • Ensure wire:model or wire:click is correctly bound.
   • Listen for custom events in Livewire:

     protected $listeners = ['carousel-item-selected' => 'handleSelection'];
     

4. Demo Routes Enabled

   • Issue: Unexpected routes appear in production.
   • Fix: Set enable_demo_routes = false in config or .env.

Tips

1. Extending Components Create child components for custom logic:

   class CustomCarousel extends Carousel {
       public function render() {
           return view('components.custom-carousel')->with([
               'items' => $this->items,
           ]);
       }
   }
   

2. Accessibility Add ARIA attributes via props:

   <x-fancy::emoji-select
       wire:model="emoji"
       aria-label="Select an emoji for your message"
   />
   

3. Dark Mode Support Use Flux’s dark mode classes or extend the package’s theme:

   'theme' => [
       'dark' => [
           'carousel' => [
               'container' => 'bg-gray-800',
           ],
       ],
   ],
   

4. Server-Side Rendering For SEO, pre-render components in Livewire’s hydrate() or use @once directives:

   @once
       <x-fancy::carousel :items="$seoItems" />
   @endonce
   

5. Performance Optimization

   • Carousel: Use lazy prop to load images on scroll.
   • Color Picker: Limit palette size with :colors="$limitedPalette".
   • Emoji Select: Pre-filter emojis by category:

     <x-fancy::emoji-select :emojis="$smileys" />