# HLCRF Layout System HLCRF (Header-Left-Content-Right-Footer) is a hierarchical, composable layout system for building complex layouts with infinite nesting. It provides flexible region-based layouts without restricting HTML structure. ## Overview Traditional Blade layouts force rigid inheritance hierarchies. HLCRF allows components to declare which layout regions they contribute to, enabling composition without structural constraints. **Use Cases:** - Admin panels and dashboards - Content management interfaces - Marketing landing pages - E-commerce product pages - Documentation sites - Any complex multi-region layout ### Traditional Blade Layouts ```blade {{-- layouts/admin.blade.php --}}

@yield('header')

@yield('content')

{{-- pages/dashboard.blade.php --}} @extends('layouts.admin') @section('header') Dashboard Header @endsection @section('content') Dashboard Content @endsection ``` **Problems:** - Rigid structure - Deep nesting - Hard to compose sections - Components can't contribute to multiple regions ### HLCRF Approach ```blade {{-- pages/dashboard.blade.php --}}

Dashboard Header

Navigation Menu

Dashboard Content

Sidebar Widgets

``` **Benefits:** - Declarative region definition - Easy composition - Components contribute to any region - No structural constraints ## Layout Regions HLCRF defines five semantic regions: ``` ┌────────────────────────────────────┐ │ Header (H) │ ├──────┬─────────────────┬───────────┤ │ │ │ │ │ Left │ Content (C) │ Right │ │ (L) │ │ (R) │ │ │ │ │ ├──────┴─────────────────┴───────────┤ │ Footer (F) │ └────────────────────────────────────┘ ``` ### Self-Documenting IDs Every HLCRF element receives a unique ID that describes its position in the DOM tree. This makes debugging, styling, and testing trivial: **ID Format:** `{Region}-{Index}-{NestedRegion}-{NestedIndex}...` **Examples:** - `H-0` = First header element - `L-1` = Second left sidebar element (0-indexed) - `C-R-2` = Content region → Right sidebar → Third element - `C-L-0-R-1` = Content → Left → First element → Right → Second element **Region Letters:** - `H` = Header - `L` = Left - `C` = Content - `R` = Right - `F` = Footer **Benefits:** 1. **Instant debugging** - See element position from DevTools 2. **Precise CSS targeting** - No class soup needed 3. **Test selectors** - Stable IDs for E2E tests 4. **Documentation** - DOM structure is self-explanatory ```html

Main content

``` **CSS Examples:** ```css /* Target specific nested elements */ #C-R-2 { width: 300px; } /* Target all right sidebars at any depth */ [id$="-R-0"] { background: #f9f9f9; } /* Target deeply nested content regions */ [id*="-C-"][id*="-C-"] { padding: 2rem; } /* Target second header element anywhere */ [id^="H-1"], [id*="-H-1"] { font-weight: bold; } ``` ### Header Region Top section for navigation, branding, global actions: ```blade ``` ### Left Region Sidebar navigation, filters, secondary navigation: ```blade ``` ### Content Region Main content area: ```blade

Dashboard

``` ### Right Region Contextual help, related actions, widgets: ```blade ``` ### Footer Region Copyright, links, status information: ```blade ``` ## Component Composition ### Multiple Components Contributing Components can contribute to multiple regions: ```blade {{-- Page header --}}

``` ### Nested Layouts HLCRF layouts can be nested infinitely. Each element receives a unique, self-documenting ID that describes its position in the DOM tree: ```blade {{-- components/post-editor.blade.php --}}

``` **Generated IDs:** ```html

``` The ID format follows the pattern: - Single letter = region type (`H`=Header, `L`=Left, `C`=Content, `R`=Right, `F`=Footer) - Number = index within that region (0-based) - Dash separates nesting levels This makes the DOM structure self-documenting and enables precise CSS targeting: ```css /* Target all right sidebars at any nesting level */ [id$="-R-0"] { /* ... */ } /* Target deeply nested content areas */ [id^="C-"][id*="-C-"] { /* ... */ } /* Target second element in any header */ [id^="H-1"] { /* ... */ } ``` ## Layout Variants ### Two-Column Layout ```blade

Navigation

Main Content

``` ### Three-Column Layout ```blade

Left Sidebar

Main Content

Right Sidebar

``` ### Full-Width Layout ```blade

Header

Full-Width Content

``` ### Modal Layout ```blade

Edit Post

Save

Cancel

``` ## Responsive Behavior HLCRF layouts adapt to screen size: ```blade

Sidebar

Content

Widgets

``` **Result:** - **Mobile:** Left → Content → Right (stacked vertically) - **Tablet:** Left | Content (side-by-side) - **Desktop:** Left | Content | Right (three columns) ## Region Options ### Collapsible Regions ```blade Navigation Menu ``` ### Fixed Regions ```blade Sticky Header ``` ### Scrollable Regions ```blade Long Content ``` ### Region Width ```blade Fixed width sidebar Percentage width sidebar ``` ## Conditional Regions ### Show/Hide Based on Conditions ```blade @auth

@endauth Main Content @can('view-admin-sidebar')

@endcan ``` ### Feature Flags ```blade Content @feature('advanced-analytics')

@endfeature ``` ## Styling ### Custom Classes ```blade

Header

Content

``` ### Slot Attributes ```blade Dark Sidebar ``` ## Real-World Examples ### Marketing Landing Page ```blade {{-- Sticky header with CTA --}} {{-- Hero section with sidebar --}}

``` ### E-Commerce Product Page ```blade

``` ### Blog with Ads ```blade

{!! $post->content !!}

``` ## Advanced Patterns ### Dynamic Region Loading ```blade

Main Content

{{-- Load widgets based on page --}} @foreach($widgets as $widget) @include("widgets.{$widget}") @endforeach

``` ### Livewire Integration ```blade

@livewire('global-search')

@livewire('post-list')

@livewire('post-filters')

``` ### Portal Teleportation Send content to regions from anywhere: ```blade {{-- Page content --}}

My Page

Action 1

Action 2

{{-- page-actions.blade.php component --}} {{ $slot }} ``` ## Implementation ### Layout Component ```php @if($header ?? false)

@endif

@if($left ?? false)

@endif

@if($right ?? false)

@endif

@if($footer ?? false) @endif ``` ## Testing ### Component Testing ```php blade( '

Left

Content

Right

' ); $view->assertSee('Left'); $view->assertSee('Content'); $view->assertSee('Right'); } public function test_optional_regions(): void { $view = $this->blade( '

Content Only

' ); $view->assertSee('Content Only'); $view->assertDontSee('hlcrf-left'); $view->assertDontSee('hlcrf-right'); } } ``` ## Best Practices ### 1. Use Semantic Regions ```blade {{-- ✅ Good - semantic use --}} Global Navigation

Page Navigation

Main Content

Contextual Help {{-- ❌ Bad - misuse of regions --}} Sidebar Content Footer Content ``` ### 2. Keep Regions Optional ```blade {{-- ✅ Good - gracefully handles missing regions --}}

Content works without sidebars

``` ### 3. Consistent Widths ```blade {{-- ✅ Good - consistent sidebar widths --}} Nav Widgets ``` ### 4. Mobile-First ```blade {{-- ✅ Good - stack on mobile --}} ``` ## Learn More - [Admin Components](/packages/admin#components) - [Livewire Integration](/packages/admin#livewire) - [Responsive Design](/patterns-guide/responsive-design)

Dashboard

Edit Post

{{ $post->title }}

My Page