diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..1ee4d91 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,114 @@ +# Material Blade - AI Coding Agent Instructions + +## Project Overview +Material Blade is a Laravel package that wraps Google Material Design Web Components (v2) as Laravel Blade components. It bridges Material Components Web JavaScript library with Laravel's Blade templating system. + +## Architecture + +### Component Structure Pattern +Each component follows a three-part architecture: + +1. **PHP Component Class** (`src/Components/{Name}.php`) + - Extends `Illuminate\View\Component` + - Constructor parameters map to component props + - Uses enum-based properties for type-safe values (see `src/Components/Button/Properties/Variant.php`) + - Implements `attributesPreprocess()` method to merge CSS classes and HTML attributes + - Returns Blade view via `render()` method pointing to `mbv::*` namespace + +2. **Blade Template** (`src/views/components/{name}.blade.php`) + - Uses `$attributesPreprocess()` to apply computed attributes + - Wraps Material Design HTML structure + - References other components via `` namespace + +3. **Properties Directory** (`src/Components/{Name}/Properties/`) + - Contains PHP enums for component variants, severity, etc. + - All enums use the `PropertyEnum` trait for string-based initialization + - Example: `Variant::fromString('outlined')` validates and converts string to enum + +### Key Files +- `src/ServiceProvider.php`: Registers views under `mbv::` namespace and components under `mbc::` namespace; special handling for `list` and `switch` (reserved PHP keywords) +- `src/Helper.php`: Theme color utilities (`getColor()`, `isThemeColor()`) and icon parsing (`parseIconString()`) +- `src/routes.php`: Serves compiled assets via named route `material-blade.assets` +- `src/assets/src/main.ts`: Initializes Material Components Web via `autoInit()`, handles icon buttons and banners + +## Component Development Patterns + +### Adding New Components +1. Create PHP class in `src/Components/{Name}.php` extending `Component` +2. Define constructor parameters matching Material Design props +3. Create enum properties in `src/Components/{Name}/Properties/` using `PropertyEnum` trait +4. Implement `attributesPreprocess()` to merge classes: + ```php + return $attributes->merge([...])->class([ + 'mdc-{component}', + 'mdc-{component}--{variant}' => $condition, + ]); + ``` +5. Create Blade template in `src/views/components/{name}.blade.php` +6. Register in `ServiceProvider.php` if component name conflicts with PHP keywords + +### Component Naming Conventions +- PHP classes: PascalCase (e.g., `IconButton`) +- Blade files: kebab-case (e.g., `icon-button.blade.php`) +- Component usage: `` or `` +- Views: `mbv::{name}` namespace + +### Property Enum Pattern +All component variants/options use enums with `PropertyEnum` trait: +```php +enum Variant: string { + use PropertyEnum; + case OUTLINED = 'outlined'; +} +// Usage: Variant::fromString('outlined') throws exception if invalid +``` + +### HTML Tag Flexibility +Components like Button use `getHtmlTag()` to dynamically switch between `