Getting Started

Minimal Setup

Install via Composer:

composer require nuxtifyts/dash-stack-theme

Publish Configuration (if needed):

php artisan vendor:publish --provider="Nuxtifyts\DashStackTheme\DashStackThemeServiceProvider" --tag="config"

Register the Theme in app/Providers/AppServiceProvider.php:

use Nuxtifyts\DashStackTheme\DashStackTheme;

public function boot()
{
    DashStackTheme::make()
        ->register();
}

First Use Case: Apply the theme to your Filament admin panel by ensuring your AppServiceProvider or Filament panel configuration includes the theme registration before any Filament components are rendered.

Where to Look First

README.md: Focus on the Installation and Configuration sections.
Theme Assets: Check resources/views/vendor/filament/ for default views (if published).
Filament Demo App: Review the FilamentPHP demo app for integration examples.

First Use Case: Quick Theme Application

To apply the theme globally to your Filament admin panel:

// In AppServiceProvider or a dedicated Filament service provider
use Nuxtifyts\DashStackTheme\DashStackTheme;

public function boot()
{
    DashStackTheme::make()
        ->register()
        ->setDarkMode(true); // Optional: Enable dark mode by default
}

Verify the theme appears in your Filament dashboard after clearing cached views:

php artisan view:clear

Implementation Patterns

Core Workflows

Theme Registration:
- Register the theme once in your application’s boot process (e.g., AppServiceProvider).
- Use DashStackTheme::make()->register() to integrate with Filament’s view composer.
Dynamic Theme Switching:
- Override the theme per panel or user:
```
DashStackTheme::make()
    ->setDarkMode(auth()->user()->prefers_dark_mode)
    ->register();
```
- Store user preferences in the database and fetch them dynamically.
Customizing Assets:
- Publish and override default assets (e.g., CSS/JS) via:
```
php artisan vendor:publish --tag="dash-stack-theme-assets"
```
- Modify resources/views/vendor/filament/ or public/vendor/filament/ for custom styles.

Integration with Filament Panels:

Ensure the theme is registered before Filament panels are instantiated. Example:

// In a dedicated Filament service provider
public function boot()
{
    DashStackTheme::make()->register();
    // Other Filament configurations...
}

Integration Tips

Filament Panels: The theme is designed to work seamlessly with Filament’s default panels. No additional configuration is required for basic usage.
Dark Mode: Enable/disable dark mode globally or per user:
```
DashStackTheme::make()->setDarkMode(true);
```
Use Filament’s built-in dark mode utilities (e.g., useDarkMode() in Blade) for consistency.
Localization: The theme supports localization via Filament’s translation system. Override default strings in resources/lang/ if needed.

Asset Optimization: Use Laravel Mix or Vite to bundle and optimize the theme’s CSS/JS. Example vite.config.js:

import { defineConfig } from 'vite';
import Laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        Laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
    ],
});

Gotchas and Tips

Pitfalls

Registration Timing:
- Issue: Theme not applying or styles missing.
- Fix: Ensure DashStackTheme::make()->register() is called before any Filament panels or views are rendered. Place it in AppServiceProvider::boot() or a dedicated Filament service provider.
Asset Conflicts:
- Issue: Custom CSS/JS overriding theme styles.
- Fix: Use specific selectors or scope your styles. Example:
```
/* In your custom CSS */
.filament .dash-stack-theme { ... }
```
Cached Views:
- Issue: Changes to theme assets not reflecting.
- Fix: Clear cached views:
```
php artisan view:clear
```
- For production, use php artisan config:clear if theme settings are cached.
Dark Mode Inconsistencies:
- Issue: Dark mode not applying uniformly across components.
- Fix: Ensure Filament’s dark mode utilities (e.g., useDarkMode()) are consistent with the theme’s implementation. Check for conflicting CSS variables.

Debugging

Inspect Elements:
- Use browser dev tools to verify theme classes (e.g., dash-stack-theme, dark-mode) are applied to the <body> or root elements.
Check Published Assets:
- Verify assets are published to public/vendor/filament/ or resources/views/vendor/filament/. Run:
```
php artisan vendor:publish --tag="dash-stack-theme-assets" --force
```

Log Theme Registration:

Add debug logs to confirm registration:

DashStackTheme::make()->register();
\Log::info('DashStackTheme registered:', ['config' => DashStackTheme::getConfig()]);

Filament Debug Mode:

Enable Filament’s debug mode to inspect panel configurations:

Filament::serving(function () {
    \Log::info('Filament panels:', Filament::getPanels());
});

Tips

Extend the Theme:

Create a custom theme by extending DashStackTheme:

use Nuxtifyts\DashStackTheme\DashStackTheme as BaseTheme;

class CustomDashStackTheme extends BaseTheme
{
    public function configure()
    {
        parent::configure();
        $this->setPrimaryColor('#4f46e5'); // Customize colors
    }
}

Theme Configuration:

Publish the config file for customization:

php artisan vendor:publish --tag="dash-stack-theme-config"

Modify config/dash-stack-theme.php to adjust settings like:

'dark_mode' => env('DASH_STACK_THEME_DARK_MODE', false),
'primary_color' => '#3b82f6',

Performance:
- Lazy-load non-critical theme assets (e.g., JS) using Filament’s asset management:
```
DashStackTheme::make()
    ->register()
    ->setLazyLoadAssets(true);
```

Testing:

Test theme compatibility with Filament’s testing utilities:

use Filament\Testing\Tests\TestCase;

public function test_theme_applied()
{
    $this->actingAs(User::factory()->create())
         ->get('/admin')
         ->assertSee('dash-stack-theme');
}

Community Resources:
- Check the Figma template for design references.
- Monitor the GitHub issues for updates or bugs.

Dash Stack Theme Laravel Package