# Bongo Blade Package - Cursor Rules

## Project Overview

This package provides reusable Blade components and custom directives for Laravel applications within the Bongo framework. It registers form inputs, buttons, icons, and UI components via the `BladeManager` service.

## Package Structure

```
blade/
├── src/
│   ├── BladeServiceProvider.php    # Extends AbstractServiceProvider, registers BladeManager
│   ├── Services/
│   │   └── BladeManager.php        # Registers all Blade directives and includes
│   └── Views/                      # Blade component templates
│       ├── input.blade.php         # @input directive
│       ├── select.blade.php        # @select directive
│       ├── checkbox.blade.php      # @checkbox directive
│       ├── textarea.blade.php      # @textarea directive
│       ├── multiselect.blade.php   # @multiSelect directive
│       ├── wysiwyg.blade.php       # @wysiwyg directive
│       ├── label.blade.php         # @label directive
│       ├── static.blade.php        # @static directive (read-only display)
│       ├── button_*.blade.php      # Button directives (@createButton, @editButton, etc.)
│       ├── card.blade.php          # Card component
│       ├── breadcrumbs.blade.php   # Breadcrumb navigation
│       ├── message.blade.php       # Flash message display (success, warning, danger, info)
│       ├── error.blade.php         # Validation error display
│       ├── error_icon.blade.php    # Error icon partial
│       ├── content_header.blade.php # Content header partial
│       ├── content_body.blade.php  # Content body wrapper
│       └── icons/                  # SVG icon components
│           ├── dashboard.blade.php
│           ├── user.blade.php
│           ├── page.blade.php
│           ├── post.blade.php
│           ├── menu.blade.php
│           ├── gallery.blade.php
│           ├── form.blade.php
│           ├── image.blade.php
│           ├── component.blade.php
│           ├── layout.blade.php
│           ├── document.blade.php
│           ├── estimate.blade.php
│           ├── project.blade.php
│           ├── review.blade.php
│           ├── design.blade.php
│           ├── setting.blade.php
│           ├── lock.blade.php
│           └── redirect.blade.php
└── tests/
    ├── TestCase.php                # Orchestra Testbench setup
    ├── Unit/.gitkeep
    └── Feature/.gitkeep
```

## Architecture and Design Decisions

### Service Provider Pattern

**BladeServiceProvider** extends `Bongo\Framework\Providers\AbstractServiceProvider`:
- Sets `$module = 'blade'` for view namespace registration
- Binds `BladeManager` to the service container as `blade_manager`
- Calls `BladeManager::register()` in `boot()` to register all directives

### Directive Registration Strategy

**BladeManager** registers directives using two methods:

1. **Custom Directives**: `@formgroup` / `@endformgroup` - Structural wrapper directives
2. **Blade Includes**: All other directives use `Blade::include()` for component-based rendering
   - `@input` → `blade::input`
   - `@select` → `blade::select`
   - `@checkbox` → `blade::checkbox`
   - `@createButton` → `blade::button_create`
   - etc.

### View Namespace

All views are registered under the `blade::` namespace via AbstractServiceProvider's auto-loading.

## Coding Conventions

### Naming Conventions

- **Directives**: camelCase (`@input`, `@createButton`, `@multiSelect`)
- **View Files**: snake_case (`input.blade.php`, `button_create.blade.php`)
- **Parameters**: snake_case arrays passed to directives
- **Classes**: PascalCase following PSR-4 (`BladeManager`, `BladeServiceProvider`)

### Component Parameter Patterns

All components accept parameter arrays. Common parameters:

**Form Fields**:
- `name` (required): Field name
- `label` (optional): Display label (auto-generated from name if omitted)
- `value` (optional): Field value (works with `old()` helper)
- `placeholder` (optional): Placeholder text
- `required` (optional): Marks field as required
- `disabled` (optional): Disables the field
- `class` (optional): Additional CSS classes
- `id` (optional): Custom field ID (defaults to slugified name)

**Buttons**:
- `name` (optional): Button text (defaults vary by button type)
- `url` (required for links): Target URL
- `class` (optional): Additional CSS classes

**Example Usage**:
```blade
@input(['label' => 'First Name', 'name' => 'first_name', 'value' => $user->first_name, 'required' => true])

@select(['label' => 'Department', 'name' => 'department_id', 'value' => $user->department_id, 'options' => $departments])

@createButton(['name' => 'Create User', 'url' => route('user.create')])

@checkbox(['label' => 'Is Active', 'name' => 'is_active', 'value' => $user->is_active])
```

### CSS Framework

All components use **Tailwind CSS** utility classes:
- Form inputs: `form-input`, `form-checkbox`
- Error states: `border-red-300`, `text-red-900`
- Buttons: `bg-gray-600`, `hover:bg-gray-700`
- Shadows: `shadow-sm`, `shadow-xl`
- Rounded corners: `rounded-sm`

## Common Tasks Guide

### Adding a New Form Component

1. Create view file in `src/Views/{component_name}.blade.php`
2. Include common partials: `@include('blade::label')`, `@include('blade::error')`
3. Add error state styling: `{{ $errors->has($name) ? 'border-red-300...' : '' }}`
4. Support `old()` helper: `value="{{ old($name, $value ?? null) }}"`
5. Register in `BladeManager::register()`:
```php
protected function register{ComponentName}Directive(): void
{
    Blade::include('blade::{component_name}', 'componentName');
}
```
6. Call registration method in `register()` method

### Adding a New Button Type

1. Create `src/Views/button_{type}.blade.php`
2. Follow existing button structure with SVG icon and Tailwind classes
3. Accept `$url`, `$name`, `$class` parameters
4. Add tooltip: `v-tooltip='"Action description"'`
5. Register in `BladeManager`:
```php
protected function register{Type}ButtonDirective(): void
{
    Blade::include('blade::button_{type}', '{type}Button');
}
```

### Adding a New Icon

1. Create `src/Views/icons/{icon_name}.blade.php`
2. Use SVG with `currentColor` for stroke/fill
3. Set `viewBox="0 0 24 24"` for consistency
4. Include in other views: `@include('blade::icons.{icon_name}')`

### Modifying Validation Error Display

Error handling is centralized in:
- `src/Views/error.blade.php` - Individual field errors
- `src/Views/error_icon.blade.php` - Error icon overlay
- `src/Views/message.blade.php` - Flash messages (session-based)

### Testing Components

Tests use Orchestra Testbench:
```php
// tests/Feature/ComponentTest.php
use Bongo\Blade\Tests\TestCase;

class ComponentTest extends TestCase
{
    public function test_input_renders()
    {
        $view = $this->blade('@input(["name" => "email"])');
        $this->assertStringContainsString('name="email"', $view);
    }
}
```

## Testing and Commands

### Running Tests
```bash
vendor/bin/phpunit
```

### Code Style
```bash
# Check code style
vendor/bin/pint --test

# Fix code style
vendor/bin/pint
```

### Static Analysis
```bash
vendor/bin/phpstan analyse
```

## Dependencies

**Runtime**:
- `bongo/framework` ^3.0 - Provides AbstractServiceProvider

**Development**:
- `orchestra/testbench` ^8.0 - Laravel package testing
- `laravel/pint` ^1.0 - Code style fixing
- `nunomaduro/larastan` ^2.0.1 - Static analysis

## Extending bongo/framework

This package uses `AbstractServiceProvider` for:
- Automatic view registration from `src/Views/` under `blade::` namespace
- Standard `boot()` lifecycle integration
- No routes, migrations, config, or middleware needed for this package

## Important Notes

- **No Config File**: This package doesn't use configuration files
- **No Routes**: Pure view component package
- **No Models/Migrations**: UI components only
- **Session Flash Messages**: `message.blade.php` expects `session('message')` and `session('message_type')`
- **Error Bag**: All components integrate with Laravel's `$errors` view variable
- **Old Input**: Form components automatically support `old()` helper for form repopulation
- **Accessibility**: Labels use proper `for` attributes, buttons include `aria-label` and `title`
- **ID Generation**: Field IDs auto-generated as slugified version of `$name` if not provided

## Code Style Rules

- Use PHP 8.2+ features (readonly properties, union types, etc.)
- Follow Laravel Pint configuration in `.php_cs`
- Single quotes for strings (except when interpolation needed)
- Type hints on method parameters and return types
- Visibility modifiers on all properties and methods
- Blade: Use `{{ }}` for escaped output, `{!! !!}` only when HTML needed
- Blade: Prefer `@if` over `<?php if` for consistency
