# Admin Dashboard Widgets

Capell Admin uses Filament dashboard widgets for product status, content activity, and editor work queues. Widgets are registered through `CapellAdmin::registerDashboardWidget()` and rendered by `CapellDashboard`.

## Dashboards

| Dashboard enum                | When it is used                                                                |
| ----------------------------- | ------------------------------------------------------------------------------ |
| `DashboardEnum::Main`         | Normal installed admin dashboard at `/admin`.                                  |
| `DashboardEnum::NotInstalled` | Empty/setup dashboard state when Admin is not installed yet or no site exists. |
| `DashboardEnum::SystemHealth` | Reserved for system-health style dashboard integrations.                       |

The current normal Admin package ships one main dashboard page: `Capell\Admin\Filament\Pages\CapellDashboard`.

## Built-In Main Widgets

Admin registers these main dashboard widgets from `AdminServiceProvider` and `CapellAdminPlugin`:

| Widget                     | Purpose                     |
| -------------------------- | --------------------------- |
| `SiteStatsOverviewWidget`  | Site-level summary metrics. |
| `AbstractCapellInfoWidget` | Capell/package information. |

The dashboard also includes Filament's `FilamentInfoWidget`.

Resource pages can have their own alert widgets, such as page, site, type, language, and theme alerts. Those live on the resource screens rather than the dashboard.

## Settings

Dashboard settings live under **Settings -> Dashboard**. The settings schema is `DashboardSettingsSchema`.

Toggles are discovered from:

1. Widget classes registered with `CapellAdmin::registerDashboardWidget()`.
2. Legacy/default widget enum values.
3. Package contributors tagged with `DashboardSettingsContributor::TAG`.

`SyncDashboardWidgetSettingsAction` repairs missing default keys and can re-enable defaults if all known defaults were accidentally disabled.

The built-in tuning values are:

| Setting                             | Purpose                                                                              |
| ----------------------------------- | ------------------------------------------------------------------------------------ |
| `my_work_queue_limit`               | Number of editor work-queue entries.                                                 |
| `recently_published_limit`          | Number of recently published entries.                                                |
| `ai-orchestrator_spend_window_days` | Lookback window for ai-orchestrator spend aggregates when that feature is installed. |

## Add A Package Widget

Register the widget from your package service provider:

```php
<?php

declare(strict_types=1);

namespace Vendor\Package\Providers;

use Capell\Admin\Enums\DashboardEnum;
use Capell\Admin\Facades\CapellAdmin;
use Vendor\Package\Filament\Widgets\MyPackageWidget;

final class PackageServiceProvider
{
    public function boot(): void
    {
        CapellAdmin::registerDashboardWidget(MyPackageWidget::class, DashboardEnum::Main);
    }
}
```

If the widget should appear in Settings, add a settings key to the widget class if it supports that convention, or contribute the key through a tagged `DashboardSettingsContributor`.

## Contribute Settings Toggles

```php
<?php

declare(strict_types=1);

namespace Vendor\Package\Admin;

use Capell\Admin\Contracts\DashboardSettingsContributor;

final class PackageDashboardSettingsContributor implements DashboardSettingsContributor
{
    public function settingsKeys(): array
    {
        return [
            [
                'key' => 'my_package_widget',
                'label' => 'My package widget',
                'group' => 'Package',
            ],
        ];
    }
}
```

Tag the contributor in the container:

```php
$this->app->tag([PackageDashboardSettingsContributor::class], DashboardSettingsContributor::TAG);
```

Use unique keys. If two contributors return the same key, the later-loaded contributor wins.

## Related Code

| File                                                                       | Purpose                                 |
| -------------------------------------------------------------------------- | --------------------------------------- |
| `packages/admin/src/Filament/Pages/CapellDashboard.php`                    | Dashboard page and filters.             |
| `packages/admin/src/Support/CapellAdminManager.php`                        | Dashboard widget registry.              |
| `packages/admin/src/Enums/DashboardEnum.php`                               | Dashboard buckets.                      |
| `packages/admin/src/Filament/Settings/Schemas/DashboardSettingsSchema.php` | Dashboard settings UI.                  |
| `packages/admin/src/Actions/SyncDashboardWidgetSettingsAction.php`         | Default settings repair/sync.           |
| `packages/admin/src/Contracts/DashboardSettingsContributor.php`            | Package settings contribution contract. |