chandra2004/laravel-pack-ui

Laravel Pack UI

Laravel Pack UI adalah paket antarmuka enterprise dan koleksi composables modern untuk ekosistem Laravel, Inertia.js, dan Vue 3, ditenagai oleh Tailwind CSS v4 serta Google Material Symbols.

Paket ini menerapkan filosofi headless-copy (arsitektur penerbitan langsung mirip Shadcn UI dan Laravel Breeze): seluruh kode komponen, composable, dan layout disalin langsung ke direktori resources/js/ aplikasi Anda. Hal ini memberikan kebebasan mutlak dan kepemilikan penuh atas kode antarmuka tanpa beban abstraksi runtime pihak ketiga.

Daftar Isi

• Fitur Utama v2.0.0
• Prasyarat Sistem
• Panduan Instalasi
• Katalog Komponen UI
• Katalog Composables
• Contoh Penggunaan Praktis
  • 1. Universal InputField
  • 2. Server Table & Export
  • 3. Auto-Save & Offline Sync
  • 4. Rich Text Editor (Tiptap)
  • 5. Media Player
  • 6. UI Dashboard Layout
• Integrasi Backend Laravel
• Konfigurasi Lingkungan
• Panduan Migrasi ke v2.0.0
• Lisensi

Fitur Utama v2.0.0

• 30+ Komponen Antarmuka Teruji: Mencakup elemen form interaktif, navigasi bertingkat, layout modular, media interaktif, hingga visualisasi data.
• 26 Composables Modular: Solusi siap pakai untuk validasi formulir, pencegah kehilangan data (unsaved changes guard), siklus sinkronisasi luring (offline outbox pattern), manajemen tema, pemformatan, hingga aksesibilitas.
• Arsitektur Komponen Majemuk (Compound Architecture): Komponen kompleks seperti Sidebar, Skeleton, InputField, ProductGallery, dan RichTextEditor disusun secara modular dengan sub-komponen terisolasi.
• Smart Auto-Installer: Perintah Artisan cerdas yang mengaudit dependensi sistem, mengonfigurasi app.blade.php, app.js, app.css, vite.config.js, dan middleware sesi flash secara otomatis.
• Standar Desain Terpadu: Mendukung 5 dimensi kontrol visual konsisten (Desain, Warna, Gaya, Radius, dan Ukuran) dengan dukungan dark mode bawaan dan pemenuhan kontras WCAG 2.1.
• Zero Runtime Overhead: Komponen menjadi bagian langsung dari proyek Laravel Anda, mudah diubah, ditata ulang, dan dioptimalkan sesuai kebutuhan aplikasi.

Prasyarat Sistem

Panduan Instalasi

1. Pemasangan Paket via Composer

Jalankan perintah Composer di direktori utama aplikasi Laravel:

composer require chandra2004/laravel-pack-ui

2. Eksekusi Smart Installer

Jalankan perintah Artisan installer untuk mengaudit lingkungan, menginstal dependensi prasyarat, dan mempublikasikan berkas:

php artisan pack:install

Opsi eksekusi installer:

• php artisan pack:install --all : Mengotomatiskan seluruh konfirmasi instalasi dependensi Composer dan Node.
• php artisan pack:install --force : Menimpa berkas komponen, composables, atau layout yang sudah ada di direktori resources/js/.
• php artisan pack:install --all --force : Rekomendasi instalasi bersih pada proyek baru.
• php artisan pack:install --tag=pack-ui-components : Hanya mempublikasikan komponen UI.
• php artisan pack:install --tag=pack-ui-composables : Hanya mempublikasikan modul composables.
• php artisan pack:install --tag=pack-ui-layouts : Hanya mempublikasikan layout dashboard.

3. Kompilasi Aset Frontend

Setelah installer selesai, jalankan kompilasi aset frontend:

npm run dev

Katalog Komponen UI

Seluruh komponen ditempatkan di resources/js/Components/Pack/.

1. Formulir dan Input

2. Tampilan Data dan Konten

3. Navigasi dan Tata Letak

4. Umpan Balik dan Dialog

5. Media dan Utilitas Lanjutan

Katalog Composables

Seluruh composables ditempatkan di resources/js/Composables/Pack/.

1. Manajemen State & Sinkronisasi Data

2. Formulir & Interaktivitas Input

3. Data Tabel & Ekspor

4. Dialog, UI & Notifikasi

5. Utilitas & Transformasi Data

Contoh Penggunaan Praktis

1. Universal InputField

Komponen InputField menangani berbagai variasi formulir secara otomatis hanya dengan mengubah prop type:

<script setup>
import { ref } from 'vue';
import InputField from '@/Components/Pack/InputField.vue';
import ButtonSubmit from '@/Components/Pack/ButtonSubmit.vue';

const form = ref({
    fullName: '',
    email: '',
    role: 'editor',
    birthDate: '',
    bio: '',
    terms: false,
});

const isSubmitting = ref(false);

const handleSubmit = () => {
    isSubmitting.value = true;
    // Logika pengiriman form...
};
</script>

<template>
    <form @submit.prevent="handleSubmit" class="space-y-4 max-w-lg">
        <InputField
            v-model="form.fullName"
            type="text"
            label="Nama Lengkap"
            placeholder="Masukkan nama lengkap"
            required
        />

        <InputField
            v-model="form.email"
            type="email"
            label="Alamat Email"
            placeholder="nama@domain.com"
            required
        />

        <InputField
            v-model="form.role"
            type="select"
            label="Peran Pengguna"
            :options="[
                { label: 'Administrator', value: 'admin' },
                { label: 'Editor Konten', value: 'editor' },
                { label: 'Peninjau', value: 'reviewer' },
            ]"
        />

        <InputField
            v-model="form.birthDate"
            type="datepicker"
            label="Tanggal Lahir"
        />

        <InputField
            v-model="form.bio"
            type="textarea"
            label="Biografi Singkat"
            :rows="3"
        />

        <InputField
            v-model="form.terms"
            type="checkbox"
            label="Saya menyetujui syarat dan ketentuan layanan"
        />

        <ButtonSubmit :loading="isSubmitting">
            Simpan Perubahan
        </ButtonSubmit>
    </form>
</template>

2. Server Table & Export

Implementasi tabel dengan pengurutan, pencarian, dan tombol ekspor:

<script setup>
import TableComponent from '@/Components/Pack/TableComponent.vue';
import { useServerTable } from '@/Composables/Pack/useServerTable';
import { useExportTable } from '@/Composables/Pack/useExportTable';

const props = defineProps({
    users: Object, // Paginator dari Laravel Controller
});

const { query, onSort, onSearch } = useServerTable('/users');
const { exportToCsv } = useExportTable();

const columns = [
    { key: 'id', label: 'ID', sortable: true },
    { key: 'name', label: 'Nama Pengguna', sortable: true },
    { key: 'email', label: 'Email' },
    { key: 'role', label: 'Peran' },
    { key: 'created_at', label: 'Terdaftar' },
];

const handleExport = () => {
    exportToCsv(props.users.data, columns, 'daftar-pengguna.csv');
};
</script>

<template>
    <div class="space-y-4">
        <div class="flex justify-between items-center">
            <h1 class="text-xl font-bold">Daftar Pengguna</h1>
            <button
                type="button"
                @click="handleExport"
                class="px-4 py-2 bg-indigo-600 text-white rounded-lg text-sm"
            >
                Ekspor CSV
            </button>
        </div>

        <TableComponent
            :columns="columns"
            :data="users.data"
            :pagination="users"
            @sort="onSort"
            @search="onSearch"
        />
    </div>
</template>

3. Auto-Save & Offline Sync

Menyimpan draf secara otomatis saat pengguna mengetik dan mencadangkan data jika koneksi terputus:

<script setup>
import { ref, watch } from 'vue';
import { useAutoSave } from '@/Composables/Pack/useAutoSave';
import { useOfflineSync } from '@/Composables/Pack/useOfflineSync';
import AutoSaveStatus from '@/Components/Pack/AutoSaveStatus.vue';
import InputField from '@/Components/Pack/InputField.vue';
import axios from 'axios';

const documentData = ref({
    title: '',
    content: '',
});

// Composable Offline Sync (Outbox Pattern)
const { addToOutbox, isOnline } = useOfflineSync('documents_store', async (item) => {
    await axios.post('/api/documents', item);
});

// Composable Auto Save
const { status, lastSaved, triggerSave } = useAutoSave(async () => {
    if (isOnline.value) {
        await axios.post('/api/documents/draft', documentData.value);
    } else {
        await addToOutbox(documentData.value);
    }
}, { delay: 1500 });

watch(documentData, () => {
    triggerSave();
}, { deep: true });
</script>

<template>
    <div class="space-y-4 max-w-2xl">
        <div class="flex justify-between items-center">
            <h2 class="text-lg font-semibold">Tulis Dokumen</h2>
            <AutoSaveStatus :status="status" :last-saved="lastSaved" />
        </div>

        <InputField
            v-model="documentData.title"
            label="Judul Dokumen"
            placeholder="Masukkan judul..."
        />

        <InputField
            v-model="documentData.content"
            type="textarea"
            label="Isi Dokumen"
            :rows="6"
        />
    </div>
</template>

4. Rich Text Editor (Tiptap)

Editor teks dengan bilah alat lengkap dan menu mengambang:

<script setup>
import { ref } from 'vue';
import RichTextEditor from '@/Components/Pack/RichTextEditor.vue';

const articleBody = ref('<h2>Pengenalan</h2><p>Tulis artikel menarik di sini...</p>');
</script>

<template>
    <div class="max-w-3xl">
        <RichTextEditor
            v-model="articleBody"
            label="Konten Artikel"
            placeholder="Mulai menulis konten..."
        />
    </div>
</template>

5. Media Player

Pemutar video/audio dengan kustomisasi kontrol:

<script setup>
import MediaPlayer from '@/Components/Pack/MediaPlayer.vue';
</script>

<template>
    <div class="max-w-4xl">
        <MediaPlayer
            src="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
            title="Demo Video Laravel Pack UI"
            poster="/images/poster.jpg"
            :aspect-ratio="'16/9'"
        />
    </div>
</template>

6. UI Dashboard Layout

Kerangka dashboard dengan Sidebar modular dan tombol pengalih tema:

<script setup>
import UIDashboardLayout from '@/Layouts/Pack/UIDashboardLayout.vue';
import ButtonTheme from '@/Components/Pack/ButtonTheme.vue';
</script>

<template>
    <UIDashboardLayout app-name="Enterprise App">
        <template #header-actions>
            <ButtonTheme />
        </template>

        <div class="p-6">
            <h1 class="text-2xl font-bold mb-4">Ringkasan Dashboard</h1>
            <p class="text-neutral-600 dark:text-neutral-400">
                Selamat datang di sistem manajemen dashboard.
            </p>
        </div>
    </UIDashboardLayout>
</template>

Integrasi Backend Laravel

1. Flash Session Middleware (HandleInertiaRequests.php)

Agar flash session dari Controller Laravel otomatis tertangkap oleh komponen Alert dan ToastNotification, daftarkan kunci flash pada method share():

<?php

namespace App\Http\Middleware;

use Illuminate\Http\Request;
use Inertia\Middleware;

class HandleInertiaRequests extends Middleware
{
    protected $rootView = 'app';

    public function share(Request $request): array
    {
        return [
            ...parent::share($request),
            'flash' => [
                'info'    => fn() => $request->session()->get('info'),
                'success' => fn() => $request->session()->get('success'),
                'warning' => fn() => $request->session()->get('warning'),
                'error'   => fn() => $request->session()->get('error'),
                'message' => fn() => $request->session()->get('message'),
                'alert'   => fn() => $request->session()->get('alert'),
            ],
        ];
    }
}

2. Cara Mengirim Notifikasi dari Controller

// Mengirim notifikasi Toast sederhana
return redirect()->back()->with('success', 'Data profil berhasil diperbarui.');
return redirect()->back()->with('error', 'Terjadi kesalahan saat memproses data.');

// Mengirim banner Alert terstruktur
return redirect()->back()->with('alert', [
    'type'        => 'warning',
    'title'       => 'Pemberitahuan Akun',
    'message'     => 'Harap lakukan verifikasi nomor ponsel sebelum bertransaksi.',
    'variant'     => 'soft',
    'dismissible' => true,
]);

Konfigurasi Lingkungan

[!NOTE] Seluruh pengaturan di bawah ini telah dikonfigurasi secara otomatis jika Anda menggunakan perintah php artisan pack:install. Bagian ini dicantumkan sebagai referensi arsitektur teknis proyek Anda.

1. Google Material Symbols

Tambahkan pada bagian <head> di resources/views/app.blade.php:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/icon?family=Material+Icons|Material+Icons+Outlined|Material+Symbols+Outlined" rel="stylesheet">

2. Tailwind CSS v4 & Dark Mode

Pada berkas resources/css/app.css:

@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));

3. Optimasi Code Splitting (vite.config.js)

Untuk memisahkan pustaka pihak ketiga ke dalam vendor chunk dan menghindari peringatan batas ukuran berkas:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import vue from '@vitejs/plugin-vue';
import tailwindcss from '@tailwindcss/vite';
import path from 'path';

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
        vue({
            template: {
                transformAssetUrls: {
                    base: null,
                    includeAbsolute: false,
                },
            },
        }),
        tailwindcss(),
    ],
    resolve: {
        alias: {
            'ziggy-js': path.resolve('vendor/tightenco/ziggy'),
            '@': path.resolve(__dirname, './resources/js'),
        },
    },
    build: {
        chunkSizeWarningLimit: 1000,
        rollupOptions: {
            output: {
                manualChunks: {
                    vendor: ['vue', '@inertiajs/vue3', 'axios'],
                },
            },
        },
    },
});

Panduan Migrasi ke v2.0.0

Pembaruan dari versi v1.x ke v2.0.0 membawa arsitektur komponen majemuk dan peningkatan performa besar:

1. Perbarui Dependensi Composer:

   composer require chandra2004/laravel-pack-ui:^2.0
   

2. Perbarui Berkas Komponen dan Composables: Jalankan installer dengan flag --force untuk menyinkronkan pembaruan komponen ke dalam direktori aplikasi (pastikan pekerjaan sebelumnya telah dicatat di Git):

   php artisan pack:install --force
   

3. Catatan Perubahan Arsitektur v2.0.0:

   • Sidebar Majemuk: Sidebar.vue kini menggunakan compound components (SidebarHeader, SidebarNav, SidebarGroup, SidebarItem, SidebarToggle, SidebarFooter).
   • Skeleton Majemuk: Skeleton.vue menyediakan 9 sub-varian terisolasi (SkeletonAvatar, SkeletonCard, dll).
   • Komponen Baru Ditambahkan: MediaPlayer.vue, composable usePopover.js, serta penyempurnaan integrasi Leaflet & Tiptap.
   • Dukungan Tailwind CSS v4: Seluruh token styling telah diselaraskan dengan standar Tailwind CSS v4.

4. Kompilasi Ulang Aset:

   npm run build
   

Lisensi

Paket ini dirilis di bawah lisensi terbuka MIT License Copyright (c) 2026 Chandra Tri Antomo.