## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require awcodes/overlook

Ensure you're using a compatible Filament version (check the compatibility table).

Theme Integration: Add the plugin's Blade views to your custom theme's CSS file (as shown in the README). This is critical for styling consistency.

First Use Case: Register the plugin in your PanelProvider (e.g., App\Providers\Filament\PanelProvider):

use Awcodes\Overlook\OverlookPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(OverlookPlugin::make())
        ->id('admin');
}

This adds the default dashboard widget to your Filament admin panel.

Quick Customization: Override the default widget by publishing the plugin's views:
```
php artisan vendor:publish --provider="Awcodes\Overlook\OverlookPluginServiceProvider" --tag="views"
```
Then modify the published Blade files in resources/views/vendor/overlook/.

Implementation Patterns

Core Workflows

Dashboard Integration:
- Default Widget: Automatically adds an overview widget to the dashboard (e.g., /admin).
- Custom Placement: Use Filament's widget system to place the widget in specific dashboard sections:
```
->widgets([
    OverlookWidget::class,
    // Other widgets...
])
```

Data-Driven Overviews:

Custom Queries: Extend the plugin to fetch custom data (e.g., user stats, revenue metrics) by overriding the widget's query logic:

use Awcodes\Overlook\OverlookWidget;

class CustomOverlookWidget extends OverlookWidget
{
    protected function getStats(): array
    {
        return [
            'active_users' => User::active()->count(),
            'revenue' => Order::sum('amount'),
        ];
    }
}

Dynamic Widgets:

Conditional Rendering: Use Filament's widget visibility traits to show/hide the widget based on user roles or permissions:

use Filament\Widgets\Concerns\CanBeHidden;

class RoleBasedOverlookWidget extends OverlookWidget
{
    use CanBeHidden;

    protected static bool $hiddenByDefault = true;

    public static function canBeHidden(): bool
    {
        return auth()->user()->cannot('view-overview');
    }
}

Theming and Styling:
- CSS Overrides: Extend the plugin's default styles by targeting its classes (e.g., .overlook-widget) in your custom theme.
- Dark Mode: Ensure compatibility by testing the widget in both light/dark modes and adjusting colors if needed.
Localization:
- Translatable Labels: Override the widget's labels by publishing the language files:
```
php artisan vendor:publish --provider="Awcodes\Overlook\OverlookPluginServiceProvider" --tag="lang"
```
- Update the published JSON files in resources/lang/{locale}/.

Integration Tips

Filament Panels:

Works seamlessly with Filament's multi-panel setup. Register the plugin per panel if needed:

->panel(Panel::make()->id('admin')->plugin(OverlookPlugin::make()))
->panel(Panel::make()->id('editor')->plugin(OverlookPlugin::make()))

Performance:

Lazy Loading: For panels with heavy queries, defer the widget's data loading until the widget is rendered:

class LazyOverlookWidget extends OverlookWidget
{
    protected function getStats(): array
    {
        return cache()->remember('overlook_stats', now()->addHours(1), function () {
            return parent::getStats();
        });
    }
}

Testing:

Widget Tests: Test the widget in isolation using Filament's testing helpers:

use Filament\Testing\Tests\Widget;

public function test_overlook_widget()
{
    $this->actingAs($user)
        ->get('/admin')
        ->assertSee('Active Users');
}

API-Driven Data:

Fetch data from external APIs by extending the widget's data provider:

protected function getStats(): array
{
    $response = Http::get('https://api.example.com/stats');
    return $response->json();
}

Gotchas and Tips

Common Pitfalls

Theme Misconfiguration:
- Issue: Widget appears unstyled or broken.
- Fix: Ensure the @source directive is correctly added to your theme's CSS file. Verify the path matches the plugin's version (e.g., ../../../../vendor/awcodes/overlook/resources/**/*.blade.php for v4.x).
Cached Views:
- Issue: Changes to Blade views aren't reflected.
- Fix: Clear Filament's view cache:
```
php artisan filament:cache:clear
```
  Or disable caching in config/filament.php temporarily for development.
Permission Denied:
- Issue: Widget data is empty or errors occur.
- Fix: Ensure the authenticated user has the necessary permissions to access the underlying models/queries. Use Filament's gate checks if needed.
Query Performance:
- Issue: Slow dashboard load times.
- Fix: Optimize queries in getStats() or use caching (as shown in Integration Tips). Avoid eager loading unnecessary relationships.
Version Mismatches:
- Issue: Plugin fails to load or throws errors.
- Fix: Double-check the compatibility table and ensure your Filament version matches the plugin's requirements. Downgrade/upgrade as needed:
```
composer require awcodes/overlook:3.x  # For Filament 4.x
```

Debugging Tips

Log Widget Data: Add debug logs to the widget's getStats() method to inspect fetched data:

protected function getStats(): array
{
    $stats = parent::getStats();
    \Log::debug('Overlook stats:', $stats);
    return $stats;
}

Inspect Blade Output: Use Laravel's Blade debugging to see rendered output:

if (app()->environment('local')) {
    \Blade::setEchoingResolver(function ($expression) {
        return str_contains($expression, 'overlook') ? true : null;
    });
}

Disable JavaScript: Test the widget with JS disabled to catch client-side issues (e.g., chart rendering):
```
php artisan filament:test --disable-js
```

Extension Points

Custom Widget Classes: Extend OverlookWidget to create reusable variants:

namespace App\Filament\Widgets;

use Awcodes\Overlook\OverlookWidget;

class AnalyticsOverlookWidget extends OverlookWidget
{
    protected function getStats(): array
    {
        return [
            'page_views' => Analytics::count(),
            'bounce_rate' => Analytics::avg('bounce_rate'),
        ];
    }
}

Hooks and Events: Listen for the widget's events to modify behavior dynamically:

use Awcodes\Overlook\Events\StatsFetched;

StatsFetched::listen(function (array $stats) {
    $stats['custom_metric'] = getCustomMetric();
    return $stats;
});

Dynamic Widget Titles: Override the widget's title dynamically:

public static function getTitle(): string
{
    return 'Overview - ' . now()->format('Y-m-d');
}

Chart Customization: Extend the widget's chart configuration by overriding getChartData():

protected function getChartData(): array
{
    return [
        'labels' => ['Jan', 'Feb', 'Mar'],
        'datasets' => [
            [
                'label' => 'Users',
                'data' => [10, 20, 30],
            ],
        ],
    ];
}

Pro Tips

Multi-Panel Overviews: Create panel-specific widgets by passing context to the widget:
```
OverlookWidget::make()
    ->panelId('admin')
    ->panelId('editor')
```

Real-Time Updates: Use Laravel Echo/Pusher to update the widget's data without a full page reload:

// In your Filament dashboard JS
Echo.channel('overlook-updates')
    .listen('OverlookUpdated', (data) => {
        window.livewire.dispatch('

Overlook Laravel Package