Getting Started

Minimal Steps to First Use

Install the Package
```
composer require shipbytes/laravel-ui-kit
php artisan ui-kit:install
```
Follow the interactive prompts to select core features and optional modules (e.g., admin-middleware, profile).

Publish Assets

php artisan ui-kit:publish
npm install && npm run dev  # or `build` for production

Run Migrations
```
php artisan migrate
```
Test the Admin Panel
- Visit /admin (protected by default; configure middleware in app/Providers/AuthServiceProvider.php).
- Use the pre-built Users CRUD at /admin/users (Livewire-powered).

Customize the Admin Shell Edit config/admin.php to modify the sidebar navigation:

'nav' => [
    'dashboard' => ['icon' => 'home', 'label' => 'Dashboard'],
    'users' => ['icon' => 'users', 'label' => 'Users'],
],

First Use Case: Adding a New Admin Page

Create a Livewire Component
```
php artisan make:livewire Admin/Posts
```

Register the Route Add to routes/admin.php:

Route::get('/posts', Admin\Posts::class)->name('admin.posts');

Add to Sidebar Update config/admin.php:

'nav' => [
    // ...existing items
    'posts' => ['icon' => 'file-text', 'label' => 'Posts'],
],

Access the Page Visit /admin/posts—the new item appears in the sidebar with the correct icon.

Implementation Patterns

Core Workflows

1. Modular Feature Integration

Install Optional Modules Interactively
```
php artisan ui-kit:install --module=profile,analytics
```
- Modules like profile add self-service user pages (e.g., /admin/profile).
- analytics injects UTM tracking via middleware (configure in config/ui-kit.php).
Extend Existing Modules Example: Customize the support-tickets module by publishing its views:
```
php artisan vendor:publish --tag=ui-kit-support-tickets
```
Override resources/views/ui-kit/support-tickets/queue.blade.php.

2. Admin Navigation Management

Dynamic Sidebar The sidebar is driven by config/admin.php. Use this pattern for dynamic items:

'nav' => [
    'settings' => [
        'icon' => 'cog',
        'label' => 'Settings',
        'children' => [
            'billing' => ['icon' => 'credit-card', 'label' => 'Billing'],
            'api-keys' => ['icon' => 'key', 'label' => 'API Keys'],
        ],
    ],
],

Conditional Items: Use a closure in the config:

'nav' => [
    'reports' => fn() => [
        'icon' => 'chart-bar',
        'label' => 'Reports',
        'visible' => auth()->user()->can('view_reports'),
    ],
],

3. Livewire + Volt Integration

Volt for Server-Side Rendering The kit uses Volt for admin pages (e.g., /admin/users). Extend templates by publishing:
```
php artisan vendor:publish --tag=ui-kit-views
```
Override resources/views/ui-kit/layouts/app.blade.php to add global headers/footers.

Livewire Components All CRUD operations (e.g., Users) are Livewire components. Reuse patterns:

// app/Http/Livewire/Admin/Users/Index.php
public function mount()
{
    $this->query = User::query();
}

public function updateQuery()
{
    $this->query->when($this->search, fn($q) => $q->where('name', 'like', "%{$this->search}%"));
}

Reuse in Other Components: Copy the mount()/updateQuery() logic for new CRUD pages.

4. Authentication Flows

Fortify + Livewire Auth pages (login, register) use Livewire + Fortify. Customize by publishing:
```
php artisan vendor:publish --tag=ui-kit-auth
```
Override resources/views/ui-kit/auth/login.blade.php.

Admin Middleware The kit includes HandleAdminUsers middleware (published to app/Http/Middleware/HandleAdminUsers.php). Extend it:

public function handle($request, Closure $next)
{
    if (!$request->user()?->is_admin && !config('ui-kit.admin_middleware.skip_check')) {
        abort(403);
    }
    return $next($request);
}

5. Theming and Dark Mode

Tailwind Presets The kit includes a Tailwind preset with brand colors (config('ui-kit.colors')). Extend it:

// tailwind.config.js
module.exports = {
    theme: {
        extend: {
            colors: {
                primary: config('ui-kit.colors.primary'),
                danger: config('ui-kit.colors.danger'),
            },
        },
    },
};

Dark Mode Toggle Uses Alpine.js stores (resources/js/stores/theme.js). Customize the toggle:

// resources/js/stores/theme.js
document.addEventListener('alpine:init', () => {
    Alpine.store('theme', {
        toggle() {
            this.dark = !this.dark;
            localStorage.setItem('ui-kit-theme', this.dark ? 'dark' : 'light');
        },
        init() {
            this.dark = localStorage.getItem('ui-kit-theme') === 'dark';
        },
    });
});

Integration Tips

1. With Spatie Permissions

Install the admin-middleware module:

php artisan ui-kit:install --module=admin-middleware

The kit auto-wires Spatie’s HasRoles trait. Use it in your User model:

use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;
}

Fallback to Boolean Check: If you skip the module, the middleware defaults to is_admin (add to your User model).

2. With Intervention/Image

For the profile module’s avatar uploads:
```
composer require intervention/image
```

The kit includes a StoreAvatar trait for handling uploads:

use Shipbytes\UiKit\Traits\StoreAvatar;

class User extends Authenticatable
{
    use StoreAvatar;
}

3. Customizing Emails

The kit includes Mailables for password resets/verification. Override them:
```
php artisan vendor:publish --tag=ui-kit-mailables
```
Edit resources/views/vendor/ui-kit/emails/reset-password.blade.php.

4. API Routes

The kit doesn’t include API auth by default. Add it using Laravel Sanctum/Passport:

composer require laravel/sanctum
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"

Protect API routes in routes/api.php:

Route::middleware('auth:sanctum')->group(function () {
    Route::get('/user', fn() => auth()->user());
});

5. Testing

The kit includes Pest tests for core features. Extend them by copying patterns:

// tests/Feature/Admin/UsersTest.php
public function test_users_crud()
{
    $user = User::factory()->create(['is_admin' => true]);
    actingAs($user);

    $response = get('/admin/users');
    $response->assertStatus(200);
}

Gotchas and Tips

Pitfalls

1. Middleware Registration

Issue: Forgetting to register the HandleAdminUsers middleware in app/Http/Kernel.php:

'web' => [
    // ...
    \Shipbytes\UiKit\Http\Middleware\HandleAdminUsers::class,
],

Fix: Run php artisan ui-kit:publish to publish the middleware stub.

2. Livewire Component Naming

Issue: Naming Livewire components incorrectly (e.g., AdminUser instead of Admin/Users). This breaks the kit’s auto-registration.
Fix: Use Admin/{SingularPlural} (e.g., Admin/Posts for `/admin

Laravel Ui Kit Laravel Package