Actioncrumb Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require hdaklue/actioncrumb
   

   Ensure your project meets requirements: Laravel 11+, Livewire 3+, Filament Actions 4+, Tailwind CSS, Alpine.js.

2. Publish Config (if needed):

   php artisan vendor:publish --provider="Hdaklue\Actioncrumb\ActioncrumbServiceProvider"
   

3. First Use Case: Create a Livewire component extending WireCrumb:

   use Hdaklue\Actioncrumb\Components\WireCrumb;
   use Hdaklue\Actioncrumb\{Step, Action};
   
   class UsersManagement extends WireCrumb {
       public function actioncrumbs(): array {
           return [
               Step::make('Dashboard')
                   ->url('/dashboard')
                   ->icon('heroicon-o-home'),
               Step::make('Users')
                   ->actions([
                       Action::make('Export')
                           ->icon('heroicon-o-arrow-down-tray')
                           ->url('/users/export'),
                   ]),
           ];
       }
   }
   

4. Render in Blade:

   @livewire('users-management')
   

Implementation Patterns

Core Workflows

1. Dynamic Breadcrumb Generation: Use Step::make() to define hierarchical navigation. Each step can include:

   • Static URLs (->url())
   • Dynamic routes (->route())
   • Conditional visibility (->canSee(fn() => auth()->user()->isAdmin))

2. Contextual Actions: Attach actions to steps via ->actions([...]):

   Step::make('User Profile')
       ->actions([
           Action::make('Edit')
               ->method('editUser')
               ->icon('heroicon-o-pencil'),
           Action::make('Delete')
               ->method('deleteUser')
               ->danger()
               ->requiresConfirmation(),
       ])
   

3. Livewire Integration:

   • Override actioncrumbs() to return dynamic data.
   • Use this->emit() to trigger parent component updates:

     public function editUser() {
         $this->emit('actionTriggered', ['step' => 'edit']);
     }
     

4. Filament Actions Compatibility: Convert Filament actions to ActionCrumb actions:

   use Hdaklue\Actioncrumb\Filament\FilamentAction;
   
   Step::make('Posts')
       ->actions([
           FilamentAction::fromFilamentAction(
               Filament\Actions\Action::make('Publish')
                   ->icon('heroicon-o-arrow-path')
           ),
       ])
   

5. Alpine.js Interactivity: Leverage Alpine.js for dropdown toggles and dynamic updates:

   <div x-data="{ open: false }">
       @livewire('users-management', ['open' => $open])
   </div>
   

Integration Tips

• Blade Directives: Use @actioncrumb to render steps/actions in templates:

  @actioncrumb('users-management')
  

• Middleware for Actions: Protect actions with middleware:

  Action::make('Admin Panel')
      ->middleware('admin')
      ->url('/admin')
  

• Localization: Localize step/action labels:

  Step::make(__('Dashboard'))
      ->actions([
          Action::make(__('Export'))
              ->url(route('users.export')),
      ])
  

• Testing: Mock WireCrumb components in tests:

  $this->livewire(UsersManagement::class)
      ->assertSee('Dashboard')
      ->assertSee('Export');
  

Gotchas and Tips

Pitfalls

1. Livewire Hydration Issues:

   • Problem: Actions not persisting after hydration.
   • Fix: Ensure actioncrumbs() returns consistent data:

     public function actioncrumbs(): array {
         return cache()->remember('actioncrumbs', now()->addHours(1), function() {
             return [...];
         });
     }
     

2. Tailwind Conflicts:

   • Problem: Default styles clash with your theme.
   • Fix: Override CSS in resources/css/actioncrumb.css:

     .actioncrumb-dropdown {
         @apply shadow-lg bg-white dark:bg-gray-800;
     }
     

3. Filament Action Mismatch:

   • Problem: Filament actions not rendering correctly.
   • Fix: Explicitly cast Filament actions:

     FilamentAction::fromFilamentAction(
         Filament\Actions\Action::make('Delete')
             ->color('danger')
     )->color('danger');
     

4. Performance with Large Datasets:

   • Problem: Slow rendering for deeply nested steps.
   • Fix: Lazy-load actions:

     Step::make('Users')
         ->actions(fn() => [
             // Load actions dynamically
         ])
     

Debugging

• Log Actions: Enable debug mode in config/actioncrumb.php:

  'debug' => env('APP_DEBUG', false),
  

  Logs actions to storage/logs/actioncrumb.log.

• Inspect Rendered HTML: Use browser dev tools to verify Alpine.js/x-data bindings:

  <!-- Check for missing `x-data` attributes -->
  <div x-data="...">
  

Extension Points

1. Custom Step/Action Classes: Extend Step or Action for reusable logic:

   class AdminStep extends Step {
       public function adminOnly(): static {
           return $this->canSee(fn() => auth()->user()->isAdmin);
       }
   }
   

2. Event Listeners: Listen for action triggers:

   ActionCrumb::listen('action.triggered', function($event) {
       Log::info('Action triggered:', $event->action);
   });
   

3. Service Provider Hooks: Override default behavior in AppServiceProvider:

   public function boot() {
       ActionCrumb::macro('customMacro', function($step) {
           return $step->withMeta(['custom' => true]);
       });
   }
   

4. Blade Components: Create custom views for steps/actions:

   @component('actioncrumb::step', [
       'step' => $step,
       'actions' => $actions,
   ])
   @endcomponent