README

<<<<<<< HEAD

php-mobile-ui — Laravel Mobile UI Package

======= <<<<<<< HEAD

Laravel Native Mobile UI

46a38dd77910e6d7e54f8f3015560b957cfdd758

A PHP-first, mobile-native UI component library for Laravel + Livewire v4 Built by Elegant Media for Android WebView and NativePHP applications.

🎯 One-Year Vision

This package powers the mobile storefront experience for two Elegant Media brands:

Brand	Product	Goal
Elegant Media	Internal tooling & client apps	A premium PHP component SDK that competes with Flutter's widget philosophy, without leaving Laravel
The Appliance Store	Consumer-facing mobile commerce	A high-performance product browsing, cart, and checkout UI entirely driven by Livewire v4 components

📦 Installation

composer require nativemobile/laravel-mobile-ui

The package auto-discovers its service provider via Laravel's package auto-discovery.

🗺️ Phased Roadmap

✅ Phase 1 — Foundation (Q1 2026)

Goal: Solid base that all future components inherit from.

Widget — Abstract base class with fluent CSS API and Htmlable integration:
- Spacing: ->padding(), ->paddingX(), ->paddingY(), ->margin(), ->marginX(), ->marginY()
- Appearance: ->background(), ->color(), ->borderRadius(), ->opacity(), ->shadow()
- Layout: ->width(), ->height(), ->overflow()
- Identity: ->id(), ->class(), ->attr()
Stylable contract — defines the fluent style interface
Renderable contract — render(): string
Htmlable integration — toHtml() and __toString() for seamless Blade rendering

// Works directly in Blade templates
{!! TextView::make()->text('Hello, World!')->padding('16px')->background('#6200EE')->color('#fff') !!}

// Or as a Blade variable (Htmlable autorender)
$widget = TextView::make()->text('Hello')->padding('16px');
// {{ $widget }} works without {!! !!} escaping issues

✅ Phase 2 — Layouts (Q1–Q2 2026)

Goal: Flutter-style declarative layout primitives.

Component	Description
`Column`	Vertical flex layout. `mainAxisAlignment`, `crossAxisAlignment`, `gap`, `scrollable`
`Row`	Horizontal flex layout. Same API, adds `wrap`, horizontal `scrollable`
`Stack`	Absolute-positioned layers with 9-point alignment grid
`Scaffold`	Full-screen page shell composing AppBar + body + BottomNavigation + FAB

Scaffold::make()
    ->appBar(AppBar::make()->title('Products')->withDrawer())
    ->body(
        Column::make()
            ->padding('16px')
            ->gap('12px')
            ->scrollable()
            ->children($productWidgets)
    )
    ->bottomNav(
        BottomNavigation::make()
            ->tabs(config('mobile-nav.bottom'))
            ->active('products')
            ->badges(['cart' => $cartCount])
    )

✅ Phase 3 — Navigation (Q2 2026)

Goal: Persistent, state-aware navigation with real-time badge counters.

Component	Feature
`BottomNavigation`	Real-time badge counters (dot for 1, numeric for 2–99, "99+" cap). Livewire reactive via `wire:click`.
`NavigationDrawer`	Side-panel with per-item badge support, Alpine.js open/close, Android back-button integration
`AppBar`	Android status bar color sync, drawer toggle, back button, action slots

// Real-time cart badge via Livewire property
BottomNavigation::make()
    ->tabs(config('mobile-nav.bottom'))
    ->active($this->activeTab)
    ->livewire('switchTab')
    ->badges([
        'cart'          => $this->cartCount,       // Updates reactively
        'notifications' => $this->unreadCount,
    ])
    ->badgeColor('#E53935')

✅ Phase 4 — Data (Q2–Q3 2026)

Goal: High-performance data rendering using the itemBuilder pattern from Flutter.

ListView — Closure-based list rendering:

ListView::make()
    ->items($this->products)
    ->itemBuilder(function (array $product, int $index): string {
        return Card::make()
            ->title($product['name'])
            ->subtitle('$' . $product['price'])
            ->render();
    })
    ->separator('#f0f0f0')
    ->onScrollEnd('loadMore')   // Livewire infinite scroll
    ->padding('0 16px')

🔜 Phase 5 — Livewire Single-File Components (Q3 2026)

Goal: .wire.php single-file components for reactive native-feel interactions.

<livewire:mobile.product-list /> — SFC with virtual scroll
<livewire:mobile.cart-drawer /> — Persistent cart state
<livewire:mobile.search-bar /> — Debounced live search
NativePHP v3.1 EDGE tag integration for hardware haptics and status bar

🔜 Phase 6 — Native Bridge (Q4 2026)

Goal: Deep NativePHP v3.1 integration for a true native feel.

AndroidBridge JS interface wrappers (haptics, status bar, camera, file picker)
Push notification bridge with Livewire event syncing
NativeGestureDetector for swipe, long-press, and pinch

🧩 Component Catalogue

Layout

Class	Description
`AppBar`	Fixed top bar with status bar color sync
`BottomNavigation`	Tab bar with badge counters
`NavigationDrawer`	Slide-in side menu
`Column`	Vertical flex layout
`Row`	Horizontal flex layout
`Stack`	Layered absolute positioning
`Scaffold`	Full-screen page shell
`Modal`	Bottom sheet / dialog

UI

Class	Description
`TextView`	Styled text with typography helpers
`Button`	Tap targets with haptic feedback
`Card`	Elevated content container
`Image`	Lazy-loaded with srcset
`Carousel`	Touch-swipe with Alpine.js
`ListView`	itemBuilder list renderer
`ProgressBar`	Linear or circular
`Slider`	Range input
`Link`	Accessible anchors

🧪 Testing

Tests live in packages/php-mobile-ui/tests/ and run via Pest v4.

# From the Laravel app root
php artisan test --compact --filter=mobile-ui

# From the package directory
./vendor/bin/pest

Coverage:

WidgetStylingTest — 15 tests covering all fluent CSS properties
ColumnRowTest — 14 tests for Column, Row, Stack layouts
ListViewTest — 11 tests for itemBuilder, separators, scroll wiring

⚙️ Configuration

php artisan vendor:publish --tag=mobile-ui-config

Edit config/mobile-ui.php to define your navigation tabs, brand colors, and NativePHP bridge settings.

🏢 Credits

Developed and maintained by Elegant Media — elegantmedia.com.au

Mobile commerce platform: The Appliance Store
Architecture: Mobile-first Laravel with Livewire v4
Target runtime: Android WebView via NativePHP v3.1

Licensed MIT. PHP 8.2+ required.

nativemobile / laravel-mobile-ui

Maintainers

Package info

Statistics

Security