diff --git a/docs/authorization.md b/docs/authorization.md new file mode 100644 index 0000000..a10f19b --- /dev/null +++ b/docs/authorization.md @@ -0,0 +1,559 @@ +# Authorization + +Integration with Laravel's Gate and Policy system for fine-grained authorization in admin panels. + +## Form Component Authorization + +All form components support authorization props: + +```blade + + Publish Post + +``` + +### Authorization Props + +**`can` - Single ability:** + +```blade + + Delete + + +{{-- Only shown if user can delete the post --}} +``` + +**`cannot` - Inverse check:** + +```blade + + +{{-- Disabled if user cannot publish --}} +``` + +**`canAny` - Multiple abilities (OR):** + +```blade + + Edit Post + + +{{-- Shown if user can either edit OR update --}} +``` + +## Policy Integration + +### Defining Policies + +```php +workspace_id === $post->workspace_id; + } + + public function create(User $user): bool + { + return $user->hasPermission('posts.create'); + } + + public function update(User $user, Post $post): bool + { + return $user->id === $post->author_id + || $user->hasRole('editor'); + } + + public function delete(User $user, Post $post): bool + { + return $user->hasRole('admin') + && $user->workspace_id === $post->workspace_id; + } + + public function publish(User $user, Post $post): bool + { + return $user->hasPermission('posts.publish') + && $post->status !== 'archived'; + } +} +``` + +### Registering Policies + +```php +use Illuminate\Support\Facades\Gate; +use Mod\Blog\Models\Post; +use Mod\Blog\Policies\PostPolicy; + +// In AuthServiceProvider or module Boot class +Gate::policy(Post::class, PostPolicy::class); +``` + +## Action Gate + +Use the Action Gate system for route-level authorization: + +### Defining Actions + +```php +middleware(['auth', ActionGateMiddleware::class]); + +// Protect route group +Route::middleware(['auth', ActionGateMiddleware::class]) + ->group(function () { + Route::post('/posts', [PostController::class, 'store']); + Route::post('/posts/{post}/publish', [PostController::class, 'publish']); + }); +``` + +### Checking Permissions + +```php +use Core\Bouncer\Gate\ActionGateService; + +$gate = app(ActionGateService::class); + +// Check if user can perform action +if ($gate->allows('posts.create', auth()->user())) { + // User has permission +} + +// Check with additional context +if ($gate->allows('posts.publish', auth()->user(), $post)) { + // User can publish this specific post +} + +// Get all user permissions +$permissions = $gate->getUserPermissions(auth()->user()); +``` + +## Admin Menu Authorization + +Restrict menu items by permission: + +```php +use Core\Front\Admin\Support\MenuItemBuilder; + +MenuItemBuilder::create('Posts') + ->route('admin.posts.index') + ->icon('heroicon-o-document-text') + ->can('posts.view') // Only shown if user can view posts + ->badge(fn () => Post::pending()->count()) + ->children([ + MenuItemBuilder::create('All Posts') + ->route('admin.posts.index'), + + MenuItemBuilder::create('Create Post') + ->route('admin.posts.create') + ->can('posts.create'), // Nested permission check + + MenuItemBuilder::create('Categories') + ->route('admin.categories.index') + ->canAny(['categories.view', 'categories.edit']), + ]); +``` + +## Livewire Modal Authorization + +Protect Livewire modals with authorization checks: + +```php +authorize('update', $post); + + $this->post = $post; + } + + public function save() + { + // Authorize action + $this->authorize('update', $this->post); + + $this->post->save(); + + $this->dispatch('post-updated'); + } + + public function publish() + { + // Custom authorization + $this->authorize('publish', $this->post); + + $this->post->update(['status' => 'published']); + } +} +``` + +## Workspace Scoping + +Automatic workspace isolation with policies: + +```php +class PostPolicy +{ + public function viewAny(User $user): bool + { + // User can view posts in their workspace + return true; + } + + public function view(User $user, Post $post): bool + { + // Enforce workspace boundary + return $user->workspace_id === $post->workspace_id; + } + + public function update(User $user, Post $post): bool + { + // Workspace check + additional authorization + return $user->workspace_id === $post->workspace_id + && ($user->id === $post->author_id || $user->hasRole('editor')); + } +} +``` + +## Role-Based Authorization + +### Defining Roles + +```php +use Mod\Tenant\Models\User; + +// Assign role +$user->assignRole('editor'); + +// Check role +if ($user->hasRole('admin')) { + // User is admin +} + +// Check any role +if ($user->hasAnyRole(['editor', 'author'])) { + // User has at least one role +} + +// Check all roles +if ($user->hasAllRoles(['editor', 'reviewer'])) { + // User has both roles +} +``` + +### Policy with Roles + +```php +class PostPolicy +{ + public function update(User $user, Post $post): bool + { + return $user->hasRole('admin') + || ($user->hasRole('editor') && $user->workspace_id === $post->workspace_id) + || ($user->hasRole('author') && $user->id === $post->author_id); + } + + public function delete(User $user, Post $post): bool + { + // Only admins can delete + return $user->hasRole('admin'); + } +} +``` + +## Permission-Based Authorization + +### Defining Permissions + +```php +// Grant permission +$user->givePermission('posts.create'); +$user->givePermission('posts.publish'); + +// Check permission +if ($user->hasPermission('posts.publish')) { + // User can publish +} + +// Check multiple permissions +if ($user->hasAllPermissions(['posts.create', 'posts.publish'])) { + // User has all permissions +} + +// Check any permission +if ($user->hasAnyPermission(['posts.edit', 'posts.delete'])) { + // User has at least one permission +} +``` + +### Policy with Permissions + +```php +class PostPolicy +{ + public function create(User $user): bool + { + return $user->hasPermission('posts.create'); + } + + public function publish(User $user, Post $post): bool + { + return $user->hasPermission('posts.publish') + && $post->status === 'draft'; + } +} +``` + +## Conditional Rendering + +### Blade Directives + +```blade +@can('create', App\Models\Post::class) + Create Post +@endcan + +@cannot('delete', $post) +

You cannot delete this post

+@endcannot + +@canany(['edit', 'update'], $post) + Edit +@endcanany +``` + +### Component Visibility + +```blade + + Publish + + +{{-- Automatically hidden if user cannot publish --}} +``` + +### Form Field Disabling + +```blade + + +{{-- Disabled if user cannot edit slug --}} +``` + +## Authorization Middleware + +### Global Middleware + +```php +// app/Http/Kernel.php +protected $middlewareGroups = [ + 'web' => [ + // ... + \Core\Bouncer\Gate\ActionGateMiddleware::class, + ], +]; +``` + +### Route Middleware + +```php +// Require authentication +Route::middleware(['auth'])->group(function () { + Route::get('/admin', [AdminController::class, 'index']); +}); + +// Require specific ability +Route::middleware(['can:create,App\Models\Post'])->group(function () { + Route::get('/posts/create', [PostController::class, 'create']); +}); +``` + +## Testing Authorization + +```php +use Tests\TestCase; +use Mod\Blog\Models\Post; +use Mod\Tenant\Models\User; + +class AuthorizationTest extends TestCase +{ + public function test_user_can_view_own_posts(): void + { + $user = User::factory()->create(); + $post = Post::factory()->create(['author_id' => $user->id]); + + $this->assertTrue($user->can('view', $post)); + } + + public function test_user_cannot_delete_others_posts(): void + { + $user = User::factory()->create(); + $post = Post::factory()->create(); // Different author + + $this->assertFalse($user->can('delete', $post)); + } + + public function test_admin_can_delete_any_post(): void + { + $admin = User::factory()->create(); + $admin->assignRole('admin'); + + $post = Post::factory()->create(); + + $this->assertTrue($admin->can('delete', $post)); + } + + public function test_workspace_isolation(): void + { + $user1 = User::factory()->create(['workspace_id' => 1]); + $user2 = User::factory()->create(['workspace_id' => 2]); + + $post = Post::factory()->create(['workspace_id' => 1]); + + $this->assertTrue($user1->can('view', $post)); + $this->assertFalse($user2->can('view', $post)); + } +} +``` + +## Best Practices + +### 1. Always Check Workspace Boundaries + +```php +// ✅ Good - workspace check +public function view(User $user, Post $post): bool +{ + return $user->workspace_id === $post->workspace_id; +} + +// ❌ Bad - no workspace check +public function view(User $user, Post $post): bool +{ + return true; // Data leak! +} +``` + +### 2. Use Policies Over Gates + +```php +// ✅ Good - policy +$this->authorize('update', $post); + +// ❌ Bad - manual check +if (auth()->id() !== $post->author_id) { + abort(403); +} +``` + +### 3. Authorize Early + +```php +// ✅ Good - authorize in mount +public function mount(Post $post) +{ + $this->authorize('update', $post); + $this->post = $post; +} + +// ❌ Bad - authorize in action +public function save() +{ + $this->authorize('update', $this->post); // Too late! + $this->post->save(); +} +``` + +### 4. Use Authorization Props + +```blade +{{-- ✅ Good - declarative authorization --}} + + Delete + + +{{-- ❌ Bad - manual check --}} +@if(auth()->user()->can('delete', $post)) + Delete +@endif +``` + +## Learn More + +- [Form Components →](/packages/admin/forms) +- [Admin Menus →](/packages/admin/menus) +- [Multi-Tenancy →](/packages/core/tenancy) diff --git a/docs/components-reference.md b/docs/components-reference.md new file mode 100644 index 0000000..1daaeb5 --- /dev/null +++ b/docs/components-reference.md @@ -0,0 +1,784 @@ +# Components Reference + +Complete API reference for all form components in the Admin package, including prop documentation, validation rules, authorization integration, and accessibility notes. + +## Overview + +All form components in Core PHP: +- Wrap Flux UI components with additional features +- Support authorization via `canGate` and `canResource` props +- Include ARIA accessibility attributes +- Work seamlessly with Livewire +- Follow consistent naming conventions + +## Input + +Text input with various types and authorization support. + +### Basic Usage + +```blade + +``` + +### Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `id` | string | **required** | Unique identifier for the input | +| `label` | string | `null` | Label text displayed above input | +| `helper` | string | `null` | Helper text displayed below input | +| `canGate` | string | `null` | Gate/policy ability to check | +| `canResource` | mixed | `null` | Resource to check ability against | +| `instantSave` | bool | `false` | Use `wire:model.live.debounce.500ms` | +| `type` | string | `'text'` | Input type (text, email, password, number, etc.) | +| `placeholder` | string | `null` | Placeholder text | +| `disabled` | bool | `false` | Disable the input | +| `readonly` | bool | `false` | Make input read-only | +| `required` | bool | `false` | Mark as required | +| `min` | number | `null` | Minimum value (for number inputs) | +| `max` | number | `null` | Maximum value (for number inputs) | +| `maxlength` | number | `null` | Maximum character length | + +### Authorization Example + +```blade +{{-- Input disabled if user cannot update the post --}} + +``` + +### Type Variants + +```blade +{{-- Text input --}} + + +{{-- Email input --}} + + +{{-- Password input --}} + + +{{-- Number input --}} + + +{{-- Date input --}} + + +{{-- URL input --}} + +``` + +### Instant Save Mode + +```blade +{{-- Saves with 500ms debounce --}} + +``` + +### Accessibility + +The component automatically: +- Associates label with input via `id` +- Links error messages with `aria-describedby` +- Sets `aria-invalid="true"` when validation fails +- Includes helper text in accessible description + +--- + +## Textarea + +Multi-line text input with authorization support. + +### Basic Usage + +```blade + +``` + +### Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `id` | string | **required** | Unique identifier | +| `label` | string | `null` | Label text | +| `helper` | string | `null` | Helper text | +| `canGate` | string | `null` | Gate/policy ability to check | +| `canResource` | mixed | `null` | Resource for ability check | +| `instantSave` | bool | `false` | Use live debounced binding | +| `rows` | number | `3` | Number of visible rows | +| `placeholder` | string | `null` | Placeholder text | +| `disabled` | bool | `false` | Disable the textarea | +| `maxlength` | number | `null` | Maximum character length | + +### Authorization Example + +```blade + +``` + +### With Character Limit + +```blade + +``` + +--- + +## Select + +Dropdown select with authorization support. + +### Basic Usage + +```blade + + Draft + Published + Archived + +``` + +### Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `id` | string | **required** | Unique identifier | +| `label` | string | `null` | Label text | +| `helper` | string | `null` | Helper text | +| `canGate` | string | `null` | Gate/policy ability to check | +| `canResource` | mixed | `null` | Resource for ability check | +| `instantSave` | bool | `false` | Use live binding | +| `placeholder` | string | `null` | Placeholder option text | +| `disabled` | bool | `false` | Disable the select | +| `multiple` | bool | `false` | Allow multiple selections | + +### Authorization Example + +```blade + + @foreach($categories as $category) + + {{ $category->name }} + + @endforeach + +``` + +### With Placeholder + +```blade + + United States + United Kingdom + Canada + +``` + +### Multiple Selection + +```blade + + @foreach($tags as $tag) + + {{ $tag->name }} + + @endforeach + +``` + +--- + +## Checkbox + +Single checkbox with authorization support. + +### Basic Usage + +```blade + +``` + +### Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `id` | string | **required** | Unique identifier | +| `label` | string | `null` | Label text (displayed inline) | +| `helper` | string | `null` | Helper text below checkbox | +| `canGate` | string | `null` | Gate/policy ability to check | +| `canResource` | mixed | `null` | Resource for ability check | +| `instantSave` | bool | `false` | Use live binding | +| `disabled` | bool | `false` | Disable the checkbox | +| `value` | string | `null` | Checkbox value (for arrays) | + +### Authorization Example + +```blade + +``` + +### With Helper Text + +```blade + +``` + +### Checkbox Group + +```blade +
+ Notifications + + + + + + +
+``` + +--- + +## Toggle + +Switch-style toggle with authorization support. + +### Basic Usage + +```blade + +``` + +### Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `id` | string | **required** | Unique identifier | +| `label` | string | `null` | Label text (displayed to the left) | +| `helper` | string | `null` | Helper text below toggle | +| `canGate` | string | `null` | Gate/policy ability to check | +| `canResource` | mixed | `null` | Resource for ability check | +| `instantSave` | bool | `false` | Use live binding | +| `disabled` | bool | `false` | Disable the toggle | + +### Authorization Example + +```blade + +``` + +### Instant Save + +```blade +{{-- Toggle that saves immediately --}} + +``` + +### With Helper + +```blade + +``` + +--- + +## Button + +Action button with variants and authorization support. + +### Basic Usage + +```blade + + Save Changes + +``` + +### Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `variant` | string | `'primary'` | Button style variant | +| `type` | string | `'submit'` | Button type (submit, button, reset) | +| `canGate` | string | `null` | Gate/policy ability to check | +| `canResource` | mixed | `null` | Resource for ability check | +| `disabled` | bool | `false` | Disable the button | +| `loading` | bool | `false` | Show loading state | + +### Variants + +```blade +{{-- Primary (default) --}} +Primary + +{{-- Secondary --}} +Secondary + +{{-- Danger --}} +Delete + +{{-- Ghost --}} +Cancel +``` + +### Authorization Example + +```blade +{{-- Button disabled if user cannot delete --}} + + Delete Post + +``` + +### With Loading State + +```blade + + Save + Saving... + +``` + +### As Link + +```blade + + Cancel + +``` + +--- + +## Authorization Props Reference + +All form components support authorization through consistent props. + +### How Authorization Works + +When `canGate` and `canResource` are provided, the component checks if the authenticated user can perform the specified ability on the resource: + +```php +// Equivalent PHP check +auth()->user()?->can($canGate, $canResource) +``` + +If the check fails, the component is **disabled** (not hidden). + +### Props + +| Prop | Type | Description | +|------|------|-------------| +| `canGate` | string | The ability/gate name to check (e.g., `'update'`, `'delete'`, `'publish'`) | +| `canResource` | mixed | The resource to check the ability against (usually a model instance) | + +### Examples + +**Basic Policy Check:** +```blade + +``` + +**Multiple Components with Same Auth:** +```blade +@php $canEdit = auth()->user()?->can('update', $post); @endphp + + + +Save +``` + +**Combining with Blade Directives:** +```blade +@can('update', $post) + + Save +@else +

You do not have permission to edit this post.

+@endcan +``` + +### Defining Policies + +```php +id === $post->author_id + || $user->hasRole('editor'); + } + + public function delete(User $user, Post $post): bool + { + return $user->hasRole('admin'); + } + + public function publish(User $user, Post $post): bool + { + return $user->hasPermission('posts.publish') + && $post->status === 'draft'; + } +} +``` + +--- + +## Accessibility Notes + +### ARIA Attributes + +All components automatically include appropriate ARIA attributes: + +| Attribute | Usage | +|-----------|-------| +| `aria-labelledby` | Links to label element | +| `aria-describedby` | Links to helper text and error messages | +| `aria-invalid` | Set to `true` when validation fails | +| `aria-required` | Set when field is required | +| `aria-disabled` | Set when field is disabled | + +### Label Association + +Labels are automatically associated with inputs via the `id` prop: + +```blade + + +{{-- Renders as: --}} + + Email Address + + +``` + +### Error Announcements + +Validation errors are linked to inputs and announced to screen readers: + +```blade +{{-- Component renders error with aria-describedby link --}} + + +{{-- Screen readers announce: "Email is required" --}} +``` + +### Focus Management + +- Tab order follows visual order +- Focus states are clearly visible +- Error focus moves to first invalid field + +### Keyboard Support + +| Component | Keyboard Support | +|-----------|------------------| +| Input | Standard text input | +| Textarea | Standard multiline | +| Select | Arrow keys, Enter, Escape | +| Checkbox | Space to toggle | +| Toggle | Space to toggle, Arrow keys | +| Button | Enter/Space to activate | + +--- + +## Validation Integration + +### Server-Side Validation + +Components automatically display Laravel validation errors: + +```php +// In Livewire component +protected array $rules = [ + 'title' => 'required|max:255', + 'content' => 'required', + 'status' => 'required|in:draft,published', +]; + +public function save(): void +{ + $this->validate(); + // Errors automatically shown on components +} +``` + +### Real-Time Validation + +```php +public function updated($propertyName): void +{ + $this->validateOnly($propertyName); +} +``` + +```blade +{{-- Shows validation error as user types --}} + +``` + +### Custom Error Messages + +```php +protected array $messages = [ + 'title.required' => 'Please enter a post title.', + 'content.required' => 'Post content cannot be empty.', +]; +``` + +--- + +## Complete Form Example + +```blade +
+ {{-- Title --}} + + + {{-- Slug with instant save --}} + + + {{-- Content --}} + + + {{-- Category --}} + + @foreach($categories as $category) + + {{ $category->name }} + + @endforeach + + + {{-- Status --}} + + Draft + Published + Archived + + + {{-- Featured toggle --}} + + + {{-- Newsletter checkbox --}} + + + {{-- Actions --}} +
+ + Save Changes + + + + Cancel + + + @can('delete', $post) + + Delete + + @endcan +
+ +``` + +## Learn More + +- [Form Components Guide](/packages/admin/forms) +- [Authorization](/packages/admin/authorization) +- [Creating Admin Panels](/packages/admin/creating-admin-panels) +- [Livewire Modals](/packages/admin/modals) diff --git a/docs/components.md b/docs/components.md new file mode 100644 index 0000000..7de1efe --- /dev/null +++ b/docs/components.md @@ -0,0 +1,623 @@ +# Admin Components + +Reusable UI components for building admin panels: cards, tables, stat widgets, and more. + +## Cards + +### Basic Card + +```blade + + +

Recent Posts

+ + +

Card content goes here...

+ + + View All + + +``` + +### Card with Actions + +```blade + + +

Post Statistics

+ + + Refresh + + + + +
+ {{-- Statistics content --}} +
+ +``` + +### Card Grid + +Display cards in responsive grid: + +```blade + + +

Total Posts

+

1,234

+ + + +

Published

+

856

+ + + +

Drafts

+

378

+ + +``` + +## Stat Widgets + +### Simple Stat + +```blade + +``` + +### Stat with Trend + +```blade + +``` + +**Trend Indicators:** +- Positive number: green up arrow +- Negative number: red down arrow +- Zero: neutral indicator + +### Stat with Chart + +```blade + +``` + +**Sparkline Data:** + +```php +public function getSparklineData() +{ + return [ + 120, 145, 132, 158, 170, 165, 180, 195, 185, 200 + ]; +} +``` + +### Stat Grid + +```blade +
+ + + + + + + +
+``` + +## Tables + +### Basic Table + +```blade + + + Title + Author + Status + Actions + + + @foreach($posts as $post) + + {{ $post->title }} + {{ $post->author->name }} + + + {{ $post->status }} + + + + + Edit + + + + @endforeach + +``` + +### Sortable Table + +```blade + + + + Title + + + Created + + + + {{-- Table rows --}} + +``` + +**Livewire Component:** + +```php +class PostsTable extends Component +{ + public $sortField = 'created_at'; + public $sortDirection = 'desc'; + + public function sortBy($field) + { + if ($this->sortField === $field) { + $this->sortDirection = $this->sortDirection === 'asc' ? 'desc' : 'asc'; + } else { + $this->sortField = $field; + $this->sortDirection = 'asc'; + } + } + + public function render() + { + $posts = Post::orderBy($this->sortField, $this->sortDirection) + ->paginate(20); + + return view('livewire.posts-table', compact('posts')); + } +} +``` + +### Table with Bulk Actions + +```blade + + + + + + Title + Actions + + + @foreach($posts as $post) + + + + + {{ $post->title }} + ... + + @endforeach + + +@if(count($selected) > 0) +
+

{{ count($selected) }} selected

+ Publish + Delete +
+@endif +``` + +## Badges + +### Status Badges + +```blade +Published +Draft +Archived +Scheduled +Pending +``` + +### Badge with Dot + +```blade + + Active + +``` + +### Badge with Icon + +```blade + + + ... + + Verified + +``` + +### Removable Badge + +```blade + + {{ $tag->name }} + +``` + +## Alerts + +### Basic Alert + +```blade + + Post published successfully! + + + + Failed to save post. Please try again. + + + + This post has not been reviewed yet. + + + + You have 3 draft posts. + +``` + +### Dismissible Alert + +```blade + + Post published successfully! + +``` + +### Alert with Title + +```blade + + + Pending Review + + This post requires approval before it can be published. + +``` + +## Empty States + +### Basic Empty State + +```blade + + + ... + + + + No posts yet + + + + Get started by creating your first blog post. + + + + + Create Post + + + +``` + +### Search Empty State + +```blade +@if($posts->isEmpty() && $search) + + + No results found + + + + No posts match your search for "{{ $search }}". + + + + + Clear Search + + + +@endif +``` + +## Loading States + +### Skeleton Loaders + +```blade + + + +``` + +### Loading Spinner + +```blade +
+ +
+ +
+ {{-- Content --}} +
+``` + +### Loading Overlay + +```blade +
+ {{-- Content becomes translucent while loading --}} +
+ +
+ +
+``` + +## Pagination + +```blade + + {{-- Table content --}} + + +{{ $posts->links('admin::pagination') }} +``` + +**Custom Pagination:** + +```blade + +``` + +## Modals (See Modals Documentation) + +See [Livewire Modals →](/packages/admin/modals) for full modal documentation. + +## Dropdowns + +### Basic Dropdown + +```blade + + + + Actions + + + + + Edit + + + + Duplicate + + + + + + Delete + + +``` + +### Dropdown with Icons + +```blade + + + + + + + + ... + + Edit Post + + + + + ... + + View + + +``` + +## Tabs + +```blade + + + {{-- General settings --}} + + + + {{-- SEO settings --}} + + + + {{-- Advanced settings --}} + + +``` + +## Best Practices + +### 1. Use Semantic Components + +```blade +{{-- ✅ Good - semantic component --}} + + +{{-- ❌ Bad - manual markup --}} +
+

Revenue

+ {{ $revenue }} +
+``` + +### 2. Consistent Colors + +```blade +{{-- ✅ Good - use color props --}} +Active +Inactive + +{{-- ❌ Bad - custom classes --}} +Active +``` + +### 3. Loading States + +```blade +{{-- ✅ Good - show loading state --}} +
+ +
+ +{{-- ❌ Bad - no feedback --}} + +``` + +### 4. Empty States + +```blade +{{-- ✅ Good - helpful empty state --}} +@if($posts->isEmpty()) + + + + Create First Post + + + +@endif + +{{-- ❌ Bad - no guidance --}} +@if($posts->isEmpty()) +

No posts

+@endif +``` + +## Testing Components + +```php +use Tests\TestCase; + +class ComponentsTest extends TestCase +{ + public function test_stat_widget_renders(): void + { + $view = $this->blade(''); + + $view->assertSee('Users'); + $view->assertSee('100'); + } + + public function test_badge_renders_with_color(): void + { + $view = $this->blade('Active'); + + $view->assertSee('Active'); + $view->assertSeeInOrder(['class', 'green']); + } +} +``` + +## Learn More + +- [Form Components →](/packages/admin/forms) +- [Livewire Modals →](/packages/admin/modals) +- [Authorization →](/packages/admin/authorization) diff --git a/docs/creating-admin-panels.md b/docs/creating-admin-panels.md new file mode 100644 index 0000000..9fcf1d4 --- /dev/null +++ b/docs/creating-admin-panels.md @@ -0,0 +1,931 @@ +# Creating Admin Panels + +This guide covers the complete process of creating admin panels in the Core PHP Framework, including menu registration, modal creation, and authorization integration. + +## Overview + +Admin panels in Core PHP use: +- **AdminMenuProvider** - Interface for menu registration +- **Livewire Modals** - Full-page components for admin interfaces +- **Authorization Props** - Built-in permission checking on components +- **HLCRF Layouts** - Composable layout system + +## Menu Registration with AdminMenuProvider + +### Implementing AdminMenuProvider + +The `AdminMenuProvider` interface allows modules to contribute navigation items to the admin sidebar. + +```php + 'onAdminPanel', + ]; + + public function onAdminPanel(AdminPanelBooting $event): void + { + // Register views and routes + $event->views('blog', __DIR__.'/View/Blade'); + $event->routes(fn () => require __DIR__.'/Routes/admin.php'); + + // Register menu provider + app(AdminMenuRegistry::class)->register($this); + } + + public function adminMenuItems(): array + { + return [ + // Dashboard item in standalone group + [ + 'group' => 'dashboard', + 'priority' => self::PRIORITY_HIGH, + 'item' => fn () => [ + 'label' => 'Blog Dashboard', + 'icon' => 'newspaper', + 'href' => route('admin.blog.dashboard'), + 'active' => request()->routeIs('admin.blog.dashboard'), + ], + ], + + // Service item with entitlement + [ + 'group' => 'services', + 'priority' => self::PRIORITY_NORMAL, + 'entitlement' => 'core.srv.blog', + 'item' => fn () => [ + 'label' => 'Blog', + 'icon' => 'newspaper', + 'href' => route('admin.blog.posts'), + 'active' => request()->routeIs('admin.blog.*'), + 'color' => 'blue', + 'badge' => Post::draft()->count() ?: null, + 'children' => [ + ['label' => 'All Posts', 'href' => route('admin.blog.posts'), 'icon' => 'document-text'], + ['label' => 'Categories', 'href' => route('admin.blog.categories'), 'icon' => 'folder'], + ['label' => 'Tags', 'href' => route('admin.blog.tags'), 'icon' => 'tag'], + ], + ], + ], + + // Admin-only item + [ + 'group' => 'admin', + 'priority' => self::PRIORITY_LOW, + 'admin' => true, + 'item' => fn () => [ + 'label' => 'Blog Settings', + 'icon' => 'gear', + 'href' => route('admin.blog.settings'), + 'active' => request()->routeIs('admin.blog.settings'), + ], + ], + ]; + } +} +``` + +### Menu Item Structure + +Each item in `adminMenuItems()` follows this structure: + +| Property | Type | Description | +|----------|------|-------------| +| `group` | string | Menu group: `dashboard`, `workspaces`, `services`, `settings`, `admin` | +| `priority` | int | Order within group (use `PRIORITY_*` constants) | +| `entitlement` | string | Optional workspace feature code for access | +| `permissions` | array | Optional user permission keys required | +| `admin` | bool | Requires Hades/admin user | +| `item` | Closure | Lazy-evaluated item data | + +### Priority Constants + +```php +use Core\Front\Admin\Contracts\AdminMenuProvider; + +// Available priority constants +AdminMenuProvider::PRIORITY_FIRST // 0-9: System items +AdminMenuProvider::PRIORITY_HIGH // 10-19: Primary navigation +AdminMenuProvider::PRIORITY_ABOVE_NORMAL // 20-39: Important items +AdminMenuProvider::PRIORITY_NORMAL // 40-60: Standard items (default) +AdminMenuProvider::PRIORITY_BELOW_NORMAL // 61-79: Less important +AdminMenuProvider::PRIORITY_LOW // 80-89: Rarely used +AdminMenuProvider::PRIORITY_LAST // 90-99: End items +``` + +### Menu Groups + +| Group | Description | Rendering | +|-------|-------------|-----------| +| `dashboard` | Primary entry points | Standalone items | +| `workspaces` | Workspace management | Grouped dropdown | +| `services` | Application services | Standalone items | +| `settings` | User/account settings | Grouped dropdown | +| `admin` | Platform administration | Grouped dropdown (Hades only) | + +### Using MenuItemBuilder + +For complex menus, use the fluent `MenuItemBuilder`: + +```php +use Core\Front\Admin\Support\MenuItemBuilder; + +public function adminMenuItems(): array +{ + return [ + MenuItemBuilder::make('Commerce') + ->icon('shopping-cart') + ->route('admin.commerce.dashboard') + ->inServices() + ->priority(self::PRIORITY_NORMAL) + ->entitlement('core.srv.commerce') + ->color('green') + ->badge('New', 'green') + ->activeOnRoute('admin.commerce.*') + ->children([ + MenuItemBuilder::child('Products', route('admin.commerce.products')) + ->icon('cube'), + MenuItemBuilder::child('Orders', route('admin.commerce.orders')) + ->icon('receipt') + ->badge(fn () => Order::pending()->count()), + ['separator' => true], + MenuItemBuilder::child('Settings', route('admin.commerce.settings')) + ->icon('gear'), + ]) + ->build(), + + MenuItemBuilder::make('Analytics') + ->icon('chart-line') + ->route('admin.analytics.dashboard') + ->inServices() + ->entitlement('core.srv.analytics') + ->adminOnly() // Requires admin user + ->build(), + ]; +} +``` + +### Permission Checking + +The `HasMenuPermissions` trait provides default permission handling: + +```php +use Core\Front\Admin\Concerns\HasMenuPermissions; + +class BlogMenuProvider implements AdminMenuProvider +{ + use HasMenuPermissions; + + // Override for custom global permissions + public function menuPermissions(): array + { + return ['blog.view']; + } + + // Override for custom permission logic + public function canViewMenu(?object $user, ?object $workspace): bool + { + if ($user === null) { + return false; + } + + // Custom logic + return $user->hasRole('editor') || $user->isHades(); + } +} +``` + +## Creating Livewire Modals + +Livewire modals are full-page components that provide seamless admin interfaces. + +### Basic Modal Structure + +```php + 'required|string|max:255', + 'content' => 'required|string', + 'status' => 'required|in:draft,published,archived', + ]; + + public function mount(?Post $post = null): void + { + $this->post = $post; + + if ($post) { + $this->title = $post->title; + $this->content = $post->content; + $this->status = $post->status; + } + } + + public function save(): void + { + $validated = $this->validate(); + + if ($this->post) { + $this->post->update($validated); + $message = 'Post updated successfully.'; + } else { + Post::create($validated); + $message = 'Post created successfully.'; + } + + session()->flash('success', $message); + $this->redirect(route('admin.blog.posts')); + } + + public function render(): View + { + return view('blog::admin.post-editor'); + } +} +``` + +### Modal View with HLCRF + +```blade +{{-- resources/views/admin/post-editor.blade.php --}} + + +
+

+ {{ $post ? 'Edit Post' : 'Create Post' }} +

+ + + + +
+ + + +
+ + + + + + Draft + Published + Archived + + +
+ + {{ $post ? 'Update' : 'Create' }} Post + + + + Cancel + +
+ +
+ + +
+

Publishing Tips

+
    +
  • Use descriptive titles
    • +
  • Save as draft first
    • +
  • Preview before publishing
    • +
+
+ + +``` + +### Modal with Authorization + +```php +authorize('update', $post); + + $this->post = $post; + // ... load data + } + + public function save(): void + { + // Re-authorize on save + $this->authorize('update', $this->post); + + $this->post->update([...]); + } + + public function publish(): void + { + // Different authorization for publish + $this->authorize('publish', $this->post); + + $this->post->update(['status' => 'published']); + } + + public function delete(): void + { + $this->authorize('delete', $this->post); + + $this->post->delete(); + $this->redirect(route('admin.blog.posts')); + } +} +``` + +### Modal with File Uploads + +```php + 'required|image|max:5120', // 5MB max + 'altText' => 'required|string|max:255', + ]; + + public function upload(): void + { + $this->validate(); + + $path = $this->image->store('media', 'public'); + + Media::create([ + 'path' => $path, + 'alt_text' => $this->altText, + 'mime_type' => $this->image->getMimeType(), + ]); + + $this->dispatch('media-uploaded'); + $this->reset(['image', 'altText']); + } +} +``` + +## Authorization Integration + +### Form Component Authorization Props + +All form components support authorization via `canGate` and `canResource` props: + +```blade +{{-- Button disabled if user cannot update post --}} + + Save Changes + + +{{-- Input disabled if user cannot update --}} + + +{{-- Textarea with authorization --}} + + +{{-- Select with authorization --}} + + Draft + Published + + +{{-- Toggle with authorization --}} + +``` + +### Blade Conditional Rendering + +```blade +{{-- Show only if user can create --}} +@can('create', App\Models\Post::class) + New Post +@endcan + +{{-- Show if user can edit OR delete --}} +@canany(['update', 'delete'], $post) +
+ @can('update', $post) + Edit + @endcan + + @can('delete', $post) + + @endcan +
+@endcanany + +{{-- Show message if cannot edit --}} +@cannot('update', $post) +

You cannot edit this post.

+@endcannot +``` + +### Creating Policies + +```php +isHades()) { + return true; + } + + // Enforce workspace isolation + if ($model instanceof Post && $user->workspace_id !== $model->workspace_id) { + return false; + } + + return null; // Continue to specific method + } + + public function viewAny(User $user): bool + { + return $user->hasPermission('posts.view'); + } + + public function view(User $user, Post $post): bool + { + return $user->hasPermission('posts.view'); + } + + public function create(User $user): bool + { + return $user->hasPermission('posts.create'); + } + + public function update(User $user, Post $post): bool + { + return $user->hasPermission('posts.edit') + || $user->id === $post->author_id; + } + + public function delete(User $user, Post $post): bool + { + return $user->hasRole('admin') + || ($user->hasPermission('posts.delete') && $user->id === $post->author_id); + } + + public function publish(User $user, Post $post): bool + { + return $user->hasPermission('posts.publish') + && $post->status !== 'archived'; + } +} +``` + +## Complete Module Example + +Here is a complete example of an admin module with menus, modals, and authorization. + +### Directory Structure + +``` +Mod/Blog/ +├── Boot.php +├── Models/ +│ └── Post.php +├── Policies/ +│ └── PostPolicy.php +├── View/ +│ ├── Blade/ +│ │ └── admin/ +│ │ ├── posts-list.blade.php +│ │ └── post-editor.blade.php +│ └── Modal/ +│ └── Admin/ +│ ├── PostsList.php +│ └── PostEditor.php +└── Routes/ + └── admin.php +``` + +### Boot.php + +```php + 'onAdminPanel', + ]; + + public function boot(): void + { + // Register policy + Gate::policy(Post::class, PostPolicy::class); + } + + public function onAdminPanel(AdminPanelBooting $event): void + { + // Views + $event->views('blog', __DIR__.'/View/Blade'); + + // Routes + $event->routes(fn () => require __DIR__.'/Routes/admin.php'); + + // Menu + app(AdminMenuRegistry::class)->register($this); + + // Livewire components + $event->livewire('blog.admin.posts-list', View\Modal\Admin\PostsList::class); + $event->livewire('blog.admin.post-editor', View\Modal\Admin\PostEditor::class); + } + + public function adminMenuItems(): array + { + return [ + [ + 'group' => 'services', + 'priority' => self::PRIORITY_NORMAL, + 'entitlement' => 'core.srv.blog', + 'permissions' => ['posts.view'], + 'item' => fn () => [ + 'label' => 'Blog', + 'icon' => 'newspaper', + 'href' => route('admin.blog.posts'), + 'active' => request()->routeIs('admin.blog.*'), + 'color' => 'blue', + 'badge' => $this->getDraftCount(), + 'children' => [ + [ + 'label' => 'All Posts', + 'href' => route('admin.blog.posts'), + 'icon' => 'document-text', + 'active' => request()->routeIs('admin.blog.posts'), + ], + [ + 'label' => 'Create Post', + 'href' => route('admin.blog.posts.create'), + 'icon' => 'plus', + 'active' => request()->routeIs('admin.blog.posts.create'), + ], + ], + ], + ], + ]; + } + + protected function getDraftCount(): ?int + { + $count = Post::draft()->count(); + return $count > 0 ? $count : null; + } +} +``` + +### Routes/admin.php + +```php +prefix('admin/blog') + ->name('admin.blog.') + ->group(function () { + Route::get('/posts', PostsList::class)->name('posts'); + Route::get('/posts/create', PostEditor::class)->name('posts.create'); + Route::get('/posts/{post}/edit', PostEditor::class)->name('posts.edit'); + }); +``` + +### View/Modal/Admin/PostsList.php + +```php +resetPage(); + } + + #[Computed] + public function posts() + { + return Post::query() + ->when($this->search, fn ($q) => $q->where('title', 'like', "%{$this->search}%")) + ->when($this->status, fn ($q) => $q->where('status', $this->status)) + ->orderByDesc('created_at') + ->paginate(20); + } + + public function delete(int $postId): void + { + $post = Post::findOrFail($postId); + + $this->authorize('delete', $post); + + $post->delete(); + + session()->flash('success', 'Post deleted.'); + } + + public function render(): View + { + return view('blog::admin.posts-list'); + } +} +``` + +### View/Blade/admin/posts-list.blade.php + +```blade + + +
+

Blog Posts

+ + @can('create', \Mod\Blog\Models\Post::class) + + + New Post + + @endcan +
+ + + + {{-- Filters --}} +
+ + + + All Statuses + Draft + Published + +
+ + {{-- Posts table --}} +
+ + + + + + + + + + + @forelse($this->posts as $post) + + + + + + + @empty + + + + @endforelse + +
TitleStatusDateActions
{{ $post->title }} + + {{ ucfirst($post->status) }} + + {{ $post->created_at->format('M d, Y') }} + @can('update', $post) + + Edit + + @endcan + + @can('delete', $post) + + @endcan +
+ No posts found. +
+
+ + {{-- Pagination --}} +
+ {{ $this->posts->links() }} +
+ + +``` + +## Best Practices + +### 1. Always Use Entitlements for Services + +```php +// Menu item requires workspace entitlement +[ + 'group' => 'services', + 'entitlement' => 'core.srv.blog', // Required + 'item' => fn () => [...], +] +``` + +### 2. Authorize Early in Modals + +```php +public function mount(Post $post): void +{ + $this->authorize('update', $post); // Fail fast + $this->post = $post; +} +``` + +### 3. Use Form Component Authorization Props + +```blade +{{-- Declarative authorization --}} + + Save + + +{{-- Not manual checks --}} +@if(auth()->user()->can('update', $post)) + +@endif +``` + +### 4. Keep Menu Items Lazy + +```php +// Item closure is only evaluated when rendered +'item' => fn () => [ + 'label' => 'Posts', + 'badge' => Post::draft()->count(), // Computed at render time +], +``` + +### 5. Use HLCRF for Consistent Layouts + +```blade +{{-- Always use HLCRF for admin views --}} + + ... + ... + +``` + +## Learn More + +- [Admin Menus](/packages/admin/menus) +- [Livewire Modals](/packages/admin/modals) +- [Form Components](/packages/admin/forms) +- [Authorization](/packages/admin/authorization) +- [HLCRF Layouts](/packages/admin/hlcrf-deep-dive) diff --git a/docs/forms.md b/docs/forms.md new file mode 100644 index 0000000..09a53f4 --- /dev/null +++ b/docs/forms.md @@ -0,0 +1,627 @@ +# Form Components + +The Admin package provides a comprehensive set of form components with consistent styling, validation, and authorization support. + +## Overview + +All form components: +- Follow consistent design patterns +- Support Laravel validation +- Include accessibility attributes (ARIA) +- Work with Livewire +- Support authorization props + +## Form Group + +Wrapper component for labels, inputs, and validation errors: + +```blade + + + +``` + +**Props:** +- `label` (string) - Field label +- `name` (string) - Field name for validation errors +- `required` (bool) - Show required indicator +- `help` (string) - Help text below field +- `error` (string) - Manual error message + +## Input + +Text input with various types: + +```blade +{{-- Text input --}} + + +{{-- Email input --}} + + +{{-- Password input --}} + + +{{-- Number input --}} + + +{{-- Date input --}} + +``` + +**Props:** +- `name` (string, required) - Input name +- `label` (string) - Label text +- `type` (string) - Input type (text, email, password, number, date, etc.) +- `value` (string) - Input value +- `placeholder` (string) - Placeholder text +- `required` (bool) - Required field +- `disabled` (bool) - Disabled state +- `readonly` (bool) - Read-only state +- `min` / `max` (number) - Min/max for number inputs + +## Textarea + +Multi-line text input: + +```blade + + +{{-- With character counter --}} + +``` + +**Props:** +- `name` (string, required) - Textarea name +- `label` (string) - Label text +- `rows` (number) - Number of rows (default: 5) +- `cols` (number) - Number of columns +- `placeholder` (string) - Placeholder text +- `maxlength` (number) - Maximum character length +- `show-counter` (bool) - Show character counter +- `required` (bool) - Required field + +## Select + +Dropdown select: + +```blade +{{-- Simple select --}} + + +{{-- With placeholder --}} + + +{{-- Multiple select --}} + + +{{-- Grouped options --}} + +``` + +**Props:** +- `name` (string, required) - Select name +- `label` (string) - Label text +- `options` (array, required) - Options array +- `value` (mixed) - Selected value(s) +- `placeholder` (string) - Placeholder option +- `multiple` (bool) - Allow multiple selections +- `required` (bool) - Required field +- `disabled` (bool) - Disabled state + +## Checkbox + +Single checkbox: + +```blade + + +{{-- With description --}} + + +{{-- Group of checkboxes --}} +
+ Permissions + + + + +
+``` + +**Props:** +- `name` (string, required) - Checkbox name +- `label` (string) - Label text +- `value` (string) - Checkbox value +- `checked` (bool) - Checked state +- `description` (string) - Help text below checkbox +- `disabled` (bool) - Disabled state + +## Toggle + +Switch-style toggle: + +```blade + + +{{-- With colors --}} + +``` + +**Props:** +- `name` (string, required) - Toggle name +- `label` (string) - Label text +- `checked` (bool) - Checked state +- `description` (string) - Help text +- `color` (string) - Toggle color (green, blue, red) +- `disabled` (bool) - Disabled state + +## Button + +Action buttons with variants: + +```blade +{{-- Primary button --}} + + Save Changes + + +{{-- Secondary button --}} + + Cancel + + +{{-- Danger button --}} + + Delete Post + + +{{-- Ghost button --}} + + Reset + + +{{-- Icon button --}} + + + + +{{-- Loading state --}} + + Save + Saving... + +``` + +**Props:** +- `type` (string) - Button type (button, submit, reset) +- `variant` (string) - Style variant (primary, secondary, danger, ghost, icon) +- `href` (string) - Link URL (renders as ``) +- `loading` (bool) - Show loading state +- `disabled` (bool) - Disabled state +- `size` (string) - Size (sm, md, lg) + +## Authorization Props + +All form components support authorization attributes: + +```blade + + Create Post + + + + + + Delete + +``` + +**Authorization Props:** +- `can` (string) - Gate/policy check +- `can-arguments` (array) - Arguments for gate check +- `cannot` (string) - Inverse of `can` +- `hidden-unless` (string) - Hide element unless authorized +- `readonly-unless` (string) - Make readonly unless authorized +- `disabled-unless` (string) - Disable unless authorized + +[Learn more about Authorization →](/packages/admin/authorization) + +## Livewire Integration + +All components work seamlessly with Livewire: + +```blade +
+ + + + + + + + Save Post + + +``` + +### Real-Time Validation + +```blade + + +@error('slug') +

{{ $message }}

+@enderror +``` + +### Debounced Input + +```blade + +``` + +## Validation + +Components automatically show validation errors: + +```blade +{{-- Controller validation --}} +$request->validate([ + 'title' => 'required|max:255', + 'content' => 'required', + 'status' => 'required|in:draft,published', +]); + +{{-- Blade template --}} + + + +{{-- Validation errors automatically displayed --}} +``` + +### Custom Error Messages + +```blade + + + +``` + +## Complete Form Example + +```blade +
+ @csrf + +
+ {{-- Title --}} + + + + + {{-- Slug --}} + + + + + {{-- Content --}} + + + + + {{-- Status --}} + + + + + {{-- Category --}} + + + + + {{-- Options --}} +
+ + + +
+ + {{-- Actions --}} +
+ + Save Post + + + + Cancel + + + + Delete + +
+
+
+``` + +## Styling + +Components use Tailwind CSS and can be customized: + +```blade + +``` + +### Custom Wrapper Classes + +```blade + + + +``` + +## Best Practices + +### 1. Always Use Form Groups + +```blade +{{-- ✅ Good - wrapped in form-group --}} + + + + +{{-- ❌ Bad - no form-group --}} + +``` + +### 2. Use Old Values + +```blade +{{-- ✅ Good - preserves input on validation errors --}} + + +{{-- ❌ Bad - loses input on validation errors --}} + +``` + +### 3. Provide Helpful Placeholders + +```blade +{{-- ✅ Good - clear placeholder --}} + + +{{-- ❌ Bad - vague placeholder --}} + +``` + +### 4. Use Authorization Props + +```blade +{{-- ✅ Good - respects permissions --}} + + Delete + +``` + +## Learn More + +- [Livewire Modals →](/packages/admin/modals) +- [Authorization →](/packages/admin/authorization) +- [HLCRF Layouts →](/packages/admin/hlcrf) diff --git a/docs/hlcrf-deep-dive.md b/docs/hlcrf-deep-dive.md new file mode 100644 index 0000000..f153cbe --- /dev/null +++ b/docs/hlcrf-deep-dive.md @@ -0,0 +1,843 @@ +# HLCRF Deep Dive + +This guide provides an in-depth look at the HLCRF (Header-Left-Content-Right-Footer) layout system, covering all layout combinations, the ID system, responsive patterns, and complex real-world examples. + +## Layout Combinations + +HLCRF supports any combination of its five regions. The variant name describes which regions are present. + +### All Possible Combinations + +| Variant | Regions | Use Case | +|---------|---------|----------| +| `C` | Content only | Simple content pages | +| `HC` | Header + Content | Landing pages | +| `CF` | Content + Footer | Article pages | +| `HCF` | Header + Content + Footer | Standard pages | +| `LC` | Left + Content | App with navigation | +| `CR` | Content + Right | Content with sidebar | +| `LCR` | Left + Content + Right | Three-column layout | +| `HLC` | Header + Left + Content | Admin dashboard | +| `HCR` | Header + Content + Right | Blog with widgets | +| `LCF` | Left + Content + Footer | App with footer | +| `CRF` | Content + Right + Footer | Blog layout | +| `HLCF` | Header + Left + Content + Footer | Standard admin | +| `HCRF` | Header + Content + Right + Footer | Blog layout | +| `HLCR` | Header + Left + Content + Right | Full admin | +| `LCRF` | Left + Content + Right + Footer | Complex app | +| `HLCRF` | All five regions | Complete layout | + +### Content-Only (C) + +Minimal layout for simple content: + +```php +use Core\Front\Components\Layout; + +$layout = Layout::make('C') + ->c('
Simple content without chrome
'); + +echo $layout->render(); +``` + +**Output:** +```html +
+
+
+
+
Simple content without chrome
+
+
+
+
+``` + +### Header + Content + Footer (HCF) + +Standard page layout: + +```php +$layout = Layout::make('HCF') + ->h('') + ->c('
Page Content
') + ->f('
Copyright 2026
'); +``` + +### Left + Content (LC) + +Application with navigation sidebar: + +```php +$layout = Layout::make('LC') + ->l('') + ->c('
App Content
'); +``` + +### Three-Column (LCR) + +Full three-column layout: + +```php +$layout = Layout::make('LCR') + ->l('') + ->c('
Content
') + ->r(''); +``` + +### Full Admin (HLCRF) + +Complete admin panel: + +```php +$layout = Layout::make('HLCRF') + ->h('
Admin Header
') + ->l('') + ->c('
Dashboard
') + ->r('') + ->f('
Status Bar
'); +``` + +## The ID System + +Every HLCRF element receives a unique, hierarchical ID that describes its position in the layout tree. + +### ID Format + +``` +{Region}-{Index}[-{NestedRegion}-{NestedIndex}]... +``` + +**Components:** +- **Region Letter** - `H`, `L`, `C`, `R`, or `F` +- **Index** - Zero-based position within that slot (0, 1, 2, ...) +- **Nesting** - Dash-separated chain for nested layouts + +### Region Letters + +| Letter | Region | Semantic Role | +|--------|--------|---------------| +| `H` | Header | Top navigation, branding | +| `L` | Left | Primary sidebar, navigation | +| `C` | Content | Main content area | +| `R` | Right | Secondary sidebar, widgets | +| `F` | Footer | Bottom links, copyright | + +### ID Examples + +**Simple layout:** +```html +
+
+
First header element
+
Second header element
+
+
+
First content element
+
+
+``` + +**Nested layout:** +```html +
+
+
+ +
+ +
+
Nested content
+
+
+
+
+
+``` + +### ID Interpretation + +| ID | Meaning | +|----|---------| +| `H-0` | First element in Header | +| `L-2` | Third element in Left sidebar | +| `C-0` | First element in Content | +| `C-L-0` | Content > Left > First element | +| `C-R-2` | Content > Right > Third element | +| `C-L-0-R-1` | Content > Left > First > Right > Second | +| `H-0-C-0-L-0` | Header > Content > Left (deeply nested) | + +### Using IDs for CSS + +The ID system enables precise CSS targeting: + +```css +/* Target first header element */ +[data-block="H-0"] { + background: #1a1a2e; +} + +/* Target all elements in left sidebar */ +[data-slot="L"] > [data-block] { + padding: 1rem; +} + +/* Target nested content areas */ +[data-block*="-C-"] { + margin: 2rem; +} + +/* Target second element in any right sidebar */ +[data-block$="-R-1"] { + border-top: 1px solid #e5e7eb; +} + +/* Target deeply nested layouts */ +[data-layout*="-"][data-layout*="-"] { + background: #f9fafb; +} +``` + +### Using IDs for Testing + +```php +// PHPUnit/Pest +$this->assertSee('[data-block="H-0"]'); +$this->assertSeeInOrder(['[data-slot="L"]', '[data-slot="C"]']); + +// Playwright/Cypress +await page.locator('[data-block="C-0"]').click(); +await expect(page.locator('[data-slot="R"]')).toBeVisible(); +``` + +### Using IDs for JavaScript + +```javascript +// Target specific elements +const header = document.querySelector('[data-block="H-0"]'); +const sidebar = document.querySelector('[data-slot="L"]'); + +// Dynamic targeting +function getContentBlock(index) { + return document.querySelector(`[data-block="C-${index}"]`); +} + +// Nested targeting +const nestedLeft = document.querySelector('[data-block="C-L-0"]'); +``` + +## Responsive Design Patterns + +### Mobile-First Stacking + +On mobile, stack regions vertically: + +```blade + + Navigation + Content + Widgets + +``` + +**Behavior:** +- **Mobile (< 768px):** Left -> Content -> Right (vertical) +- **Tablet (768px-1024px):** Left | Content (two columns) +- **Desktop (> 1024px):** Left | Content | Right (three columns) + +### Collapsible Sidebars + +```blade + +
+ @if(!$sidebarCollapsed) + Full navigation content + @else + Icons only + @endif +
+ +``` + +### Hidden Regions on Mobile + +```blade + +``` + +### Flexible Width Distribution + +```blade + + + Fixed-width sidebar + + + + Flexible content + + + + Percentage-width sidebar + + +``` + +### Responsive Grid Inside Content + +```blade + +
+ + + +
+ +``` + +## Complex Real-World Examples + +### Admin Dashboard + +A complete admin dashboard with nested layouts: + +```php +use Core\Front\Components\Layout; + +// Main admin layout +$admin = Layout::make('HLCF') + ->h( + '' + ) + ->l( + '
' + ) + ->c( + // Nested layout inside content + Layout::make('HCR') + ->h('
+

Dashboard

+ +
') + ->c('
+
+
Stat 1
+
Stat 2
+
Stat 3
+
+
+

Recent Activity

+ ...
+
+
') + ->r('') + ) + ->f( + '
+ Version 1.0.0 | Last sync: 5 minutes ago +
' + ); + +echo $admin->render(); +``` + +**Generated IDs:** +- `H-0` - Admin header/navigation +- `L-0` - Sidebar navigation +- `C-0` - Nested layout container +- `C-0-H-0` - Content header (page title/actions) +- `C-0-C-0` - Content main area (stats/table) +- `C-0-R-0` - Content right sidebar (quick actions) +- `F-0` - Admin footer + +### E-Commerce Product Page + +Product page with nested sections: + +```php +$productPage = Layout::make('HCF') + ->h('
+ +
Search | Cart | Account
+
') + ->c( + Layout::make('LCR') + ->l('
+
+ Product +
+
+ + +
+
') + ->c( + // Empty - using left/right only + ) + ->r('
+

Product Name

+

$99.99

+

Product description...

+ +
+ + +
+ +
+

Shipping Info

+

Free delivery over $50

+
+
'), + // Reviews section + Layout::make('CR') + ->c('
+

Customer Reviews

+
+
Review 1...
+
Review 2...
+
+
') + ->r('') + ) + ->f('
+
+
About Us
+
Customer Service
+
Policies
+
Newsletter
+
+
'); +``` + +### Multi-Panel Settings Page + +Settings page with multiple nested panels: + +```php +$settings = Layout::make('HLC') + ->h('
+

Account Settings

+
') + ->l('') + ->c( + // Profile section + Layout::make('HCF') + ->h('
+

Profile Information

+

Update your account details

+
') + ->c('
+
+ + +
+
+ + +
+
+ + +
+
') + ->f('
+ + +
') + ); +``` + +### Documentation Site + +Documentation layout with table of contents: + +```php +$docs = Layout::make('HLCRF') + ->h('
+
+
+ + +
+
+ + GitHub +
+
+
') + ->l('') + ->c('
+

Introduction

+

Welcome to the documentation...

+ +

Key Features

+
    +
  • Feature 1
    • +
  • Feature 2
    • +
  • Feature 3
    • +
+ +

Next Steps

+

Continue to the installation guide...

+
') + ->r('') + ->f(''); +``` + +### Email Client Interface + +Complex email client with multiple nested panels: + +```php +$email = Layout::make('HLCR') + ->h('
+
+ + +
+
+ +
+
+ +
JD
+
+
') + ->l('') + ->c( + Layout::make('LC') + ->l('
+
+ +
+
+
+
+ John Smith + 10:30 AM +
+
Meeting Tomorrow
+
Hi, just wanted to confirm...
+
+
+
+ Jane Doe + Yesterday +
+
Project Update
+
Here is the latest update...
+
+
+
') + ->c('
+
+ + + + + + +
+
+
+

Meeting Tomorrow

+
+
JS
+
+
John Smith <john@example.com>
+
to me
+
+
Jan 15, 2026, 10:30 AM
+
+
+
+

Hi,

+

Just wanted to confirm our meeting tomorrow at 2pm.

+

Best regards,
John

+
+
+
') + ) + ->r(''); +``` + +## Performance Considerations + +### Lazy Content Loading + +For large layouts, defer non-critical content: + +```php +$layout = Layout::make('LCR') + ->l('') + ->c('
+
Loading...
+
@livewire("content-panel")
+
') + ->r(fn () => view('widgets.sidebar')); // Closure defers evaluation +``` + +### Conditional Region Rendering + +Only render regions when needed: + +```php +$layout = Layout::make('LCR'); + +$layout->l(''); +$layout->c('
Content
'); + +// Conditionally add right sidebar +if ($user->hasFeature('widgets')) { + $layout->r(''); +} +``` + +### Efficient CSS Targeting + +Use data attributes instead of deep selectors: + +```css +/* Efficient - uses data attribute */ +[data-block="C-0"] { padding: 1rem; } + +/* Less efficient - deep selector */ +.hlcrf-layout > .hlcrf-body > .hlcrf-content > div:first-child { padding: 1rem; } +``` + +## Testing HLCRF Layouts + +### Unit Testing + +```php +use Core\Front\Components\Layout; +use PHPUnit\Framework\TestCase; + +class LayoutTest extends TestCase +{ + public function test_generates_correct_ids(): void + { + $layout = Layout::make('LC') + ->l('Left') + ->c('Content'); + + $html = $layout->render(); + + $this->assertStringContainsString('data-slot="L"', $html); + $this->assertStringContainsString('data-slot="C"', $html); + $this->assertStringContainsString('data-block="L-0"', $html); + $this->assertStringContainsString('data-block="C-0"', $html); + } + + public function test_nested_layout_ids(): void + { + $nested = Layout::make('LR') + ->l('Nested Left') + ->r('Nested Right'); + + $outer = Layout::make('C') + ->c($nested); + + $html = $outer->render(); + + $this->assertStringContainsString('data-block="C-0-L-0"', $html); + $this->assertStringContainsString('data-block="C-0-R-0"', $html); + } +} +``` + +### Browser Testing + +```php +// Pest with Playwright +it('renders admin layout correctly', function () { + $this->browse(function ($browser) { + $browser->visit('/admin') + ->assertPresent('[data-layout="root"]') + ->assertPresent('[data-slot="H"]') + ->assertPresent('[data-slot="L"]') + ->assertPresent('[data-slot="C"]'); + }); +}); +``` + +## Best Practices + +### 1. Use Semantic Region Names + +```php +// Good - semantic use +->h('') +->l('') +->c('
Page content
') +->r('') +->f('
Site footer
') + +// Bad - misuse of regions +->h('') // Header for sidebar? +``` + +### 2. Leverage the ID System + +```css +/* Target specific elements precisely */ +[data-block="H-0"] { /* Header first element */ } +[data-block="C-L-0"] { /* Content > Left > First */ } + +/* Don't fight the system with complex selectors */ +``` + +### 3. Keep Nesting Shallow + +```php +// Good - 2-3 levels max +Layout::make('HCF') + ->c(Layout::make('LCR')->...); + +// Avoid - too deep +Layout::make('C') + ->c(Layout::make('C') + ->c(Layout::make('C') + ->c(Layout::make('C')...)))); +``` + +### 4. Use Consistent Widths + +```php +// Good - consistent sidebar widths across app +->l('