Filament Progress Bar Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require devletes/filament-progress-bar
   php artisan filament:assets
   

   No additional Tailwind configuration is needed—the package includes its own stylesheet.

2. First Use Case (Table Column):

   use Devletes\FilamentProgressBar\Tables\Columns\ProgressBarColumn;
   
   ProgressBarColumn::make('used')
       ->maxValue(fn ($record) => $record->quota)
       ->showProgressValue()
       ->showPercentage();
   

3. First Use Case (Infolist Entry):

   use Devletes\FilamentProgressBar\Infolists\Components\ProgressBarEntry;
   
   ProgressBarEntry::make('leave_progress')
       ->label('Sick Leave')
       ->getStateUsing(fn ($record) => [
           'progress' => $record->leave_used,
           'total' => $record->leave_total,
       ]);
   

Where to Look First

• Documentation: The README covers all features with visual examples.
• API Reference: Focus on ProgressBarColumn for tables and ProgressBarEntry for infolists.
• Recipes: Pre-built examples (e.g., battery/fuel, multi-state scores) in the "Recipes" section.

Implementation Patterns

Core Workflows

1. Data Provisioning:

   • Use maxValue() for numeric states (e.g., ->maxValue(fn ($record) => $record->quota)).
   • Use state() or getStateUsing() for structured arrays (e.g., ['progress' => 50, 'total' => 100]).
   • Flexible key matching (e.g., progress, current, used for current value; total, max for total).

2. Threshold Configuration:

   • Default 3-state: Adjust thresholds with warningThreshold() and dangerThreshold().

     ->warningThreshold(70)
     ->dangerThreshold(90)
     

   • Descending Direction: For "low is bad" metrics (e.g., battery).

     ->thresholdDirection('descending')
     ->warningThreshold(30)
     ->dangerThreshold(10)
     

   • Custom Maps: For >3 states or non-linear thresholds.

     ->thresholds([80 => 'success', 60 => 'warning', 0 => 'danger'])
     

3. Styling:

   • Size: size('sm' | 'md' | 'lg') (default: sm).
   • Text Position: textPosition('inside' | 'outside') (default: inside).
   • Border Radius: Override with CSS values (e.g., ->borderRadius('4px')).
   • Visibility: Toggle showPercentage(), hideProgressValue(), etc.

4. Dynamic Behavior:

   • Use closures for dynamic colors/labels (e.g., ->successColor(fn ($record) => $record->is_priority ? '#7c3aed' : null)).
   • Closures receive $record, $percentage, $status, etc.

Integration Tips

• Consistency: Reuse the same threshold logic across tables/infolists for uniformity.
• Dark Mode: The package is dark-mode aware—no extra config needed.
• Accessibility: Uses role="progressbar" for screen readers.
• Performance: Self-contained stylesheet minimizes bundle impact.

Common Patterns

Gotchas and Tips

Pitfalls

1. Threshold Direction:

   • Forgetting to set thresholdDirection('descending') for "low is bad" metrics (e.g., battery) will invert the thresholds.
   • Fix: Always specify direction explicitly for clarity.

2. Zero Total Handling:

   • If total is null or 0, the percentage resolves to 0% (no error).
   • Tip: Validate total in your closure if needed:

     ->state(fn ($record) => [
         'progress' => $record->used,
         'total' => $record->quota ?? 1, // Ensure non-zero
     ])
     

3. CSS Injection:

   • borderRadius() silently drops invalid CSS (e.g., ;, <, {). Stick to standard values like 4px or 0.5rem.
   • Workaround: Use null to reset to default pill shape.

4. Closure Parameters:

   • Closures for colors/labels receive $percentage and $status after resolution. Use these for dynamic logic:

     ->dangerLabel(fn (int $percentage) => "Critical ($percentage%)")
     

5. Infolist vs. Table:

   • Infolist entries support labels (e.g., ->successLabel('On track')), but table columns intentionally omit them for compactness.
   • Tip: Use infolists for detailed views and tables for quick scans.

Debugging Tips

1. Inspect State:

   • Log the resolved state to debug:

     ->state(fn ($record) => {
         $state = ['progress' => $record->used, 'total' => $record->quota];
         \Log::debug('ProgressBar state:', $state);
         return $state;
     })
     

2. Threshold Debugging:

   • Add a temporary label to verify thresholds:

     ->dangerLabel(fn (int $percentage) => "Debug: $percentage%")
     

3. Color Overrides:

   • If colors don’t apply, check:
     • Filament’s CSS variables (e.g., var(--primary-500)) are defined in your panel.
     • Custom status colors are registered via statusColors().

4. Performance:

   • Avoid heavy closures in loops (e.g., ->maxValue(fn ($record) => expensiveCalc($record))). Cache results if needed.

Extension Points

1. Custom Statuses:

   • Extend Filament’s colors with ->colors([...]) in your panel config:

     FilamentPanel::make()->colors([
         'info' => '#3b82f6',
     ]);
     

   • Then use in thresholds:

     ->thresholds([60 => 'info', 0 => 'danger'])
     

2. Global Defaults:

   • Override defaults in a service provider:

     ProgressBarColumn::macro('defaultWarningThreshold', fn () => 80);
     

3. Dark Mode Tweaks:

   • Extend the package’s stylesheet via your Tailwind config:

     /* resources/css/filament/progress-bar.css */
     .dark .filament-progress-bar-fill {
         background-color: rgba(255, 255, 255, 0.1);
     }
     

4. Localization:

   • Translate labels dynamically:

     ->dangerLabel(fn () => __("Only {current} left", ['current' => $current]))
     

Pro Tips

• Reusable Components: Create a trait or helper for common progress bars:

  trait UsesProgressBar {
      protected function batteryProgressBar(string $field): ProgressBarColumn {
          return ProgressBarColumn::make($field)
              ->thresholdDirection('descending')
              ->warningThreshold(30)
              ->dangerThreshold(10);
      }
  }
  

• Testing: Use ->getStateUsing() for predictable test data:

  $column->getStateUsing(fn () => ['progress' => 50, 'total' => 100]);
  

• Accessibility: Add ARIA labels for screen readers:

  ->extraAttributes(['aria-label' => 'Usage progress'])