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:

📦 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.

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.

// 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

UI

🧪 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.