Litepie Layout Builder

A powerful and flexible Laravel package for building dynamic, data-driven layouts with support for nested sections, components, authorization, caching, and responsive behavior.

Overview

Litepie Layout Builder provides a fluent, declarative API for creating complex UI layouts in Laravel applications. It separates layout structure from presentation logic, making it easy to build reusable, maintainable, and testable UI components.

Key Features

Declarative Layout API - Build layouts using a fluent, chainable interface
Sections & Components - Clear separation between containers (Sections) and content (Components)
Named Section Slots - Organize content in header, body, footer, and custom slots
Authorization - Built-in permission and role-based access control
Data Binding - Automatic data loading from multiple sources (API, database, closures)
Responsive Design - Device-specific layout configurations
Caching - Performance optimization with flexible cache strategies
Events - Lifecycle hooks for before/after rendering
Validation - Input validation with Laravel validator integration
Internationalization - Multi-language support with automatic translation
Export/Import - JSON serialization for layout persistence

Installation

Requirements

PHP 8.1 or higher
Laravel 10.x or 11.x

Install via Composer

composer require litepie/layout

Publish Configuration (Optional)

php artisan vendor:publish --provider="Litepie\Layout\LayoutServiceProvider"

This creates config/layout.php where you can customize default behavior.

Quick Start

Basic Example

use Litepie\Layout\Facades\Layout;

// Create a simple card layout
$layout = Layout::create('dashboard')
    ->section('main', function ($section) {
        $section->card('user-stats')
            ->title('User Statistics')
            ->dataUrl('/api/stats')
            ->addField('total_users', 'Total Users')
            ->addField('active_users', 'Active Today')
            ->addField('new_registrations', 'New This Month');
    });

// Render to array (for JSON API responses)
return $layout->render();

Creating a Form

use Litepie\Layout\Facades\Layout;

$layout = Layout::create('user-form')
    ->section('main', function ($section) {
        $section->form('user-form')
            ->action('/users')
            ->method('POST')
            ->addField('name', 'text', 'Full Name')
            ->addField('email', 'email', 'Email Address')
            ->addField('role', 'select', 'Role', ['options' => ['admin', 'user', 'guest']])
            ->addButton('submit', 'Save User', 'primary');
    });

return $layout->render();

Multi-Section Layout

use Litepie\Layout\Facades\Layout;

$layout = Layout::create('dashboard')
    ->section('header', function ($section) {
        $section->breadcrumb('navigation')
            ->addItem('Home', '/')
            ->addItem('Dashboard', '/dashboard');
    })
    ->section('main', function ($section) {
        // Grid layout with multiple cards
        $section->grid('stats-grid')
            ->columns(3)
            ->addComponent(
                $section->card('revenue')
                    ->title('Revenue')
                    ->dataUrl('/api/revenue')
            )
            ->addComponent(
                $section->card('orders')
                    ->title('Orders')
                    ->dataUrl('/api/orders')
            )
            ->addComponent(
                $section->card('customers')
                    ->title('Customers')
                    ->dataUrl('/api/customers')
            );
    })
    ->section('footer', function ($section) {
        $section->text('copyright')
            ->content('© 2025 Your Company');
    });

return $layout->render();

Core Concepts

Sections vs Components

The layout system has two fundamental building blocks:

Sections (Containers)

Sections are containers that organize other elements using named slots (header, body, footer, sidebar, etc.). They define structure but don't render content themselves.

Available Sections:

HeaderSection - Page headers with navigation
LayoutSection - Main layout containers
GridSection - Responsive grid layouts
TabsSection - Tabbed interfaces
AccordionSection - Collapsible panels
WizardSection - Multi-step workflows
ScrollSpySection - Scroll-based navigation

Components (Content)

Components are leaf nodes that render actual content. They cannot contain other elements.

Available Components:

FormComponent - Forms with fields and validation
CardComponent - Content cards
TableComponent - Data tables with sorting/filtering
ListComponent - Lists (ordered, unordered, definitions)
AlertComponent - Notifications and messages
BadgeComponent - Labels and tags
ModalComponent - Dialogs and popups
ChartComponent - Data visualizations
TextComponent - Rich text content
MediaComponent - Images, videos, galleries
StatsComponent - Statistics displays
TimelineComponent - Event timelines
CommentComponent - Comment threads
BreadcrumbComponent - Navigation breadcrumbs
DocumentComponent - Document management
CustomComponent - Custom HTML/JSON content

Section Slots

Sections organize content using named slots:

$layout->section('main', function ($section) {
    // Add to 'header' slot
    $section->section('header')->text('title')->content('Dashboard');
    
    // Add to 'body' slot (default)
    $section->card('main-content')->title('Content');
    
    // Add to 'footer' slot
    $section->section('footer')->text('info')->content('Last updated: Today');
});

Nesting Rules

✅ Sections can contain Sections - Create nested layouts
✅ Sections can contain Components - Add content to containers
❌ Components cannot contain anything - They are leaf nodes

Architecture

High-Level Structure

Layout (Root Container)
├── Section (e.g., "header")
│   ├── Component (e.g., Breadcrumb)
│   └── Component (e.g., Alert)
├── Section (e.g., "main")
│   ├── Section (e.g., Grid)
│   │   ├── Component (e.g., Card)
│   │   ├── Component (e.g., Table)
│   │   └── Component (e.g., Chart)
│   └── Section (e.g., Tabs)
│       ├── Tab 1 → Component (Form)
│       └── Tab 2 → Component (List)
└── Section (e.g., "footer")
    └── Component (e.g., Text)

Class Hierarchy

BaseSection (Container with slots)
├── HeaderSection
├── LayoutSection
├── GridSection
├── TabsSection
├── AccordionSection
├── WizardSection
└── ScrollSpySection

BaseComponent (Content leaf node)
├── FormComponent
├── CardComponent
├── TableComponent
├── ListComponent
├── AlertComponent
├── BadgeComponent
├── ModalComponent
├── ChartComponent
├── TextComponent
├── MediaComponent
├── StatsComponent
├── TimelineComponent
├── CommentComponent
├── BreadcrumbComponent
├── DocumentComponent
├── AvatarComponent
├── DividerComponent
└── CustomComponent (extensible for custom components)

Features

1. Data Binding

Load data from multiple sources:

// From API endpoint
$section->card('api-data')
    ->dataUrl('/api/stats')
    ->dataParams(['filter' => 'active']);

// From database
$section->table('users')
    ->dataSource('users')
    ->dataTransform(function ($query) {
        return $query->where('active', true)->orderBy('created_at', 'desc');
    });

// From closure
$section->card('dynamic')
    ->dataSource(function () {
        return [
            'total' => User::count(),
            'active' => User::where('active', true)->count(),
        ];
    });

2. Authorization

Control visibility with permissions and roles:

$section->card('admin-panel')
    ->permissions(['manage-users', 'view-logs'])
    ->canSee(function ($user) {
        return $user->isAdmin();
    });

// Resolve authorization for current user
$layout->resolveAuthorization(auth()->user());

3. Responsive Design

Device-specific configurations:

$section->grid('responsive-grid')
    ->columns(4)
    ->setDeviceConfig('mobile', ['columns' => 1])
    ->setDeviceConfig('tablet', ['columns' => 2]);

4. Caching

Improve performance with automatic caching:

$layout->cache()
    ->ttl(3600)
    ->key('dashboard-layout')
    ->tags(['layouts', 'dashboard']);

5. Events

Hook into the rendering lifecycle:

$layout->beforeRender(function ($layout) {
    Log::info('Rendering layout: ' . $layout->getName());
});

$layout->afterRender(function ($layout, $output) {
    Log::info('Rendered layout with ' . count($output) . ' sections');
});

6. Conditional Logic

Show/hide elements based on conditions:

$section->card('premium-features')
    ->condition('user.subscription.status == "active"')
    ->condition('user.subscription.plan == "premium"');

7. Validation

Validate form inputs:

$section->form('user-form')
    ->validationRules([
        'name' => 'required|min:3|max:255',
        'email' => 'required|email|unique:users',
        'age' => 'required|integer|min:18',
    ]);

8. Internationalization

Multi-language support:

$section->card('welcome')
    ->title('layout.welcome.title')  // Translatable key
    ->translate();  // Enable translation

// Or translate specific fields
$section->form('contact')
    ->translateField('submit_button', 'forms.submit');

Documentation

Backend (PHP/Laravel)

Architecture Guide - Detailed architecture and design patterns
API Reference - Complete API documentation for all sections and components
Examples - Comprehensive usage examples and patterns
Custom Components Guide - Create project-specific components
Complete Guide - Comprehensive documentation

Frontend Implementations

Frontend Overview - Overview of all frontend implementations
React/Next.js - ✅ Complete TypeScript implementation with Tailwind CSS
Vue.js - 📋 Planned implementation
Flutter - 📋 Planned implementation

Code Examples (PHP)

Basic Usage - Simple layout examples
Dashboard Example - Complete dashboard with stats and charts
Avatar Component - User avatar display examples
Divider Component - Visual separator examples
Custom Components - Creating custom components

Testing

Run the test suite:

composer test

Run with coverage:

composer test:coverage

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Security

If you discover any security-related issues, please email security@litepie.com instead of using the issue tracker.

License

The MIT License (MIT). Please see LICENSE for more information.

Credits

Litepie Team
All Contributors

Support

Documentation: https://litepie.com/docs/layout
Issues: GitHub Issues
Email: support@litepie.com

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
.github		.github
config		config
docs		docs
examples		examples
resources		resources
src		src
tests		tests
.gitignore		.gitignore
API_REFERENCE.md		API_REFERENCE.md
ARCHITECTURE.md		ARCHITECTURE.md
AVATAR_COMPONENT.md		AVATAR_COMPONENT.md
CARD_COMPONENT.md		CARD_COMPONENT.md
EXAMPLES.md		EXAMPLES.md
LICENSE		LICENSE
README.md		README.md
composer.json		composer.json
pint.json		pint.json
test_cache_methods.php		test_cache_methods.php

License

Litepie/Layout

Folders and files

Latest commit

History

Repository files navigation

Litepie Layout Builder

Table of Contents

Overview

Key Features

Installation

Requirements

Install via Composer

Publish Configuration (Optional)

Quick Start

Basic Example

Creating a Form

Multi-Section Layout

Core Concepts

Sections vs Components

Sections (Containers)

Components (Content)

Section Slots

Nesting Rules

Architecture

High-Level Structure

Class Hierarchy

Features

1. Data Binding

2. Authorization

3. Responsive Design

4. Caching

5. Events

6. Conditional Logic

7. Validation

8. Internationalization

Documentation

Backend (PHP/Laravel)

Frontend Implementations

Code Examples (PHP)

Testing

Contributing

Security

License

Credits

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages