@rozaqi02/reusable-dashboard 1.1.2 → 1.1.4

package/README.md

@@ -4,7 +4,7 @@ Modul dashboard admin reusable untuk aplikasi UMKM berbasis React + Supabase.
 Mendukung berbagai domain bisnis (travel, toko online, UMKM generik) tanpa menulis ulang komponen.
 CSS sudah terbundle — tidak perlu konfigurasi Tailwind.
 
-[![version](https://img.shields.io/badge/version-1.1.1-blue)](./CHANGELOG.md)
+[![version](https://img.shields.io/badge/version-1.1.3-blue)](./CHANGELOG.md)
 [![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![npm](https://img.shields.io/badge/npm-%40rozaqi02%2Freusable--dashboard-red)](https://www.npmjs.com/package/@rozaqi02/reusable-dashboard)
 
@@ -16,13 +16,15 @@ CSS sudah terbundle — tidak perlu konfigurasi Tailwind.
 2. [Prasyarat Teknis](#2-prasyarat-teknis)
 3. [Preset yang Tersedia](#3-preset-yang-tersedia)
 4. [Quick Start — Toko Sepatu (Contoh Lengkap)](#4-quick-start--toko-sepatu)
+   - [4.5 Cara Cepat dengan 1 File Config](#45-cara-cepat-dengan-createdasboardconfig)
 5. [Quick Start — Cidika Travel](#5-quick-start--cidika-travel)
 6. [Setup Database Supabase](#6-setup-database-supabase)
 7. [Cara Membuat Adapter untuk Domain Bisnis Baru](#7-cara-membuat-adapter-untuk-domain-bisnis-baru)
 8. [Konfigurasi Widget](#8-konfigurasi-widget)
 9. [Label & Internasionalisasi](#9-label--internasionalisasi)
 10. [API Reference Lengkap](#10-api-reference-lengkap)
-11. [Pengembangan & Kontribusi](#11-pengembangan--kontribusi)
+11. [Setup Wizard — Panduan Konfigurasi Interaktif](#11-setup-wizard--panduan-konfigurasi-interaktif)
+12. [Pengembangan & Kontribusi](#12-pengembangan--kontribusi)
 
 ---
 
@@ -33,8 +35,29 @@ npm install @rozaqi02/reusable-dashboard
 npm install recharts @supabase/supabase-js
 ```
 
-> **Catatan:** CSS sudah otomatis terbundle di dalam paket ini (`dist/index.css`).
-> Tidak perlu menginstall atau mengkonfigurasi Tailwind CSS.
+### Import CSS
+
+CSS modul harus di-import secara eksplisit di file CSS utama project kamu.
+
+**Create React App** — tambahkan di `src/index.css`:
+```css
+@import "../node_modules/@rozaqi02/reusable-dashboard/dist/index.css";
+```
+
+**Vite** — tambahkan di `src/index.css` atau `src/main.jsx`:
+```css
+/* index.css */
+@import "@rozaqi02/reusable-dashboard/dist/index.css";
+```
+```jsx
+// atau di main.jsx
+import "@rozaqi02/reusable-dashboard/dist/index.css";
+```
+
+**Next.js** — tambahkan di `app/globals.css` atau `pages/_app.jsx`:
+```css
+@import "@rozaqi02/reusable-dashboard/dist/index.css";
+```
 
 ---
 
@@ -42,8 +65,8 @@ npm install recharts @supabase/supabase-js
 
 | Prasyarat | Versi Minimum | Keterangan |
 |-----------|---------------|------------|
-| Node.js | 16.x | Runtime JavaScript |
-| React | 18.0.0 | UI framework |
+| Node.js | 18.x | Runtime JavaScript (18 atau lebih baru) |
+| React | 18.0.0 | UI framework (mendukung React 19) |
 | recharts | 2.0.0 | Library chart (AreaChart, PieChart, BarChart) |
 | @supabase/supabase-js | 2.0.0 | Client Supabase untuk koneksi database |
 | Akun Supabase | — | Gratis di [supabase.com](https://supabase.com) |
@@ -57,13 +80,23 @@ Belum mendukung backend lain (Firebase, REST API, GraphQL) tanpa menulis data so
 
 Modul menyediakan **3 preset siap pakai** untuk domain bisnis yang berbeda:
 
-| Preset | Domain | Tabel Supabase yang Dibutuhkan |
-|--------|--------|-------------------------------|
-| **Cidika Travel** | Travel agency / paket wisata | `bookings`, `packages`, `package_locales`, `page_sections` |
-| **Toko Sepatu** | Toko online / e-commerce | `orders`, `order_items`, `products`, `customers` |
-| **Dummy UMKM** | UMKM generik | Bisa pakai struktur toko sepatu atau buat sendiri |
+| Preset | Domain | Tabel Supabase yang Dibutuhkan | Siap Pakai? |
+|--------|--------|-------------------------------|-------------|
+| **Cidika Travel** | Travel agency / paket wisata | `bookings`, `packages`, `package_locales`, `page_sections` | Config + Adapter + Source |
+| **Toko Sepatu** | Toko online / e-commerce | `orders`, `order_items`, `products`, `customers` | Config + Adapter + Source |
+| **Dummy UMKM** | UMKM generik (contoh domain baru) | `orders`, `products`, `customers` | Config + Adapter saja* |
+
+> *Preset **Dummy UMKM** menyediakan widget config (`dummyUmkmWidgetConfig`) dan
+> adapter (`adaptDummyUmkmData`), tetapi **tidak** menyertakan data source siap pakai.
+> Data source-nya ditulis manual — lihat contoh di
+> `examples/dummy-umkm-example/DummyUmkmDashboard.jsx` (repo GitHub).
+> Ini sengaja dijadikan **template** untuk kamu yang ingin membuat domain baru
+> (lihat [Bab 7](#7-cara-membuat-adapter-untuk-domain-bisnis-baru)).
 
-Setiap preset sudah termasuk: konfigurasi widget, data adapter, dan data source Supabase.
+Hanya **2 data source siap pakai** yang diekspor modul:
+`createCidikaSupabaseSource` dan `createTokoSepatuSupabaseSource`.
+
+Setiap preset siap pakai sudah termasuk: konfigurasi widget, data adapter, dan data source Supabase.
 
 ---
 
@@ -138,8 +171,12 @@ ALTER PUBLICATION supabase_realtime ADD TABLE public.customers;
 
 **C. Isi data contoh** (opsional, untuk testing):
 
-File seed data lengkap tersedia di:
-`examples/toko-sepatu-example/seed-data.sql` dalam repositori ini.
+File seed data lengkap tersedia di repo GitHub:
+`examples/toko-sepatu-example/seed-data.sql`.
+
+> Catatan: folder `examples/` **tidak ikut** saat `npm install` (paket npm hanya
+> berisi `dist/`). Untuk mengambil file SQL contoh, kloning repo GitHub atau
+> salin manual dari halaman repositori.
 
 **D. Aktifkan Realtime** di Supabase Dashboard:
 Database → Replication → centang tabel `orders`, `products`, `customers`.
@@ -278,6 +315,100 @@ Buka browser → dashboard tampil dengan data dari Supabase.
 
 ---
 
+## 4.5 Cara Cepat dengan `createDashboardConfig`
+
+Mulai versi **1.1.3**, modul menyediakan factory function `createDashboardConfig` yang
+mengemas semua konfigurasi (widgetConfig + dataSource + adapter + labels) menjadi
+**1 objek tunggal**. Ini cara yang lebih ringkas dan direkomendasikan untuk domain baru.
+
+```
+Sebelum (4 parameter terpisah ke hook):           Sesudah (1 objek terpadu):
+
+useReusableDashboard({                             const cfg = createDashboardConfig({
+  config: tokoSepatuWidgetConfig,                    widgetConfig: tokoSepatuWidgetConfig,
+  dataSource: source,           →→→                  dataSource: source,
+  adapter: adaptTokoSepatuData,                      adapter: adaptTokoSepatuData,
+  createEmptyState: createEmpty,                     createEmptyState: createEmpty,
+  languageCode: "id",                                languageCode: "id",
+  dateLocale: "id-ID",                               dateLocale: "id-ID",
+  labels,                                          });
+});                                                useReusableDashboard({ ...cfg, labels });
+```
+
+**Contoh penggunaan lengkap:**
+
+```jsx
+import { supabase } from "../lib/supabaseClient";
+import {
+  ReusableDashboardView,
+  useReusableDashboard,
+  createDashboardConfig,          // ← factory baru
+  tokoSepatuWidgetConfig,
+  createTokoSepatuSupabaseSource,
+  adaptTokoSepatuData,
+  createEmptyTokoSepatuData,
+} from "@rozaqi02/reusable-dashboard";
+
+import { myWidgetConfig } from "./myWidgetConfig";
+import { createMySource } from "./myDataSource";
+import { adaptMyData, createEmptyMyData } from "./myAdapter";
+
+// Buat di luar komponen — sekali saja
+const dashboardConfig = createDashboardConfig({
+  widgetConfig: myWidgetConfig,
+  dataSource: createMySource(supabase),
+  adapter: adaptMyData,
+  createEmptyState: createEmptyMyData,
+  languageCode: "id",
+  dateLocale: "id-ID",
+  // labels bisa disertakan di sini atau di-override saat render
+});
+
+const labels = { title: "Dashboard Saya", /* ... */ };
+
+export default function MyDashboard() {
+  const state = useReusableDashboard({ ...dashboardConfig, labels });
+
+  return (
+    <ReusableDashboardView
+      config={dashboardConfig.config}
+      labels={labels}
+      loading={state.loading}
+      error={state.error}
+      filters={state.filters}
+      onFilterChange={state.updateFilter}
+      onResetFilters={state.resetFilters}
+      onRefresh={state.refresh}
+      data={state.data}
+      dateLocale={dashboardConfig.dateLocale}
+      liveUpdateEnabled={state.liveUpdateEnabled}
+      supabase={supabase}               // aktifkan fitur baca tabel di wizard
+      dashboardConfig={dashboardConfig} // aktifkan validasi otomatis
+    />
+  );
+}
+```
+
+**Apa yang terjadi jika config belum lengkap?**
+
+`createDashboardConfig` menyimpan info validasi di `dashboardConfig._meta`:
+
+```javascript
+dashboardConfig._meta = {
+  isValid: true,                    // false jika ada bagian yang kurang
+  missing: [],                      // ["adapter", "dataSource"] jika belum diisi
+  hasDataSource: true,
+  hasRealtimeSupport: true,         // false jika subscribeLiveUpdate tidak ada
+  hasLabels: true,
+  widgetCount: { stats: 4, charts: 4, tableColumns: 6 },
+}
+```
+
+Jika ada bagian yang kurang, `ReusableDashboardView` secara otomatis menampilkan
+**Setup Wizard** (lihat [Bab 11](#11-setup-wizard--panduan-konfigurasi-interaktif)).
+
+---
+
 ## 5. Quick Start — Cidika Travel
 
 Ganti hanya 4 baris dari contoh Toko Sepatu di atas:
@@ -378,92 +509,235 @@ CREATE POLICY "Allow read for anon" ON public.orders
 
 ## 7. Cara Membuat Adapter untuk Domain Bisnis Baru
 
-Jika bisnis kamu tidak cocok dengan preset yang ada, kamu bisa membuat
-adapter sendiri. Adapter adalah fungsi JavaScript yang mengubah data mentah
-dari Supabase ke format yang dipahami oleh komponen dashboard.
+Bab ini adalah panduan **dari nol** untuk client yang domainnya **bukan** travel
+atau toko sepatu (misal: laundry, klinik, rental mobil, kursus, dll). Kamu hanya
+perlu menulis **3 file kecil**, tanpa pernah menyentuh kode inti modul.
+
+### 7.0 Pahami dulu alurnya (WAJIB dibaca)
+
+Modul ini memisahkan 3 tanggung jawab. Memahami peran masing-masing membuat
+sisanya gampang:
+
+```
+  DATABASE Supabase
+        │
+        ▼
+  ┌───────────────┐  "Ambil data mentah dari Supabase"
+  │ 1. DATA SOURCE │  → tahu nama tabel & kolom kamu
+  └───────────────┘  → output: objek { bookings, recent, staticCounts }
+        │
+        ▼
+  ┌───────────────┐  "Ubah data mentah → format standar dashboard"
+  │ 2. ADAPTER     │  → hitung stats, susun data chart & tabel
+  └───────────────┘  → output: objek { stats, charts, table }
+        │
+        ▼
+  ┌───────────────┐  "Tentukan WIDGET apa yang tampil & labelnya"
+  │ 3. WIDGET      │  → kartu mana, chart mana, kolom tabel mana
+  │    CONFIG      │
+  └───────────────┘
+        │
+        ▼
+  useReusableDashboard(...)  →  <ReusableDashboardView />   (UI jadi)
+```
+
+Aturan emas:
+- **Data Source** = satu-satunya bagian yang tahu nama tabel/kolom database kamu.
+- **Adapter** = satu-satunya bagian yang berisi logika hitung (revenue, konversi, dll).
+- **Widget Config** = satu-satunya bagian yang menentukan tampilan (deklaratif, tanpa logika).
+
+Urutan mengerjakan: **Data Source → Adapter → Widget Config → rangkai di halaman**.
+
+---
+
+### 7.1 Kontrak antar-lapisan (referensi cepat)
+
+**Output Data Source** (yang masuk ke adapter sebagai `raw`):
+
+```javascript
+{
+  bookings: [...],      // WAJIB. Array semua transaksi dalam rentang tanggal.
+  recent: [...],        // WAJIB. Array 10 transaksi terbaru (untuk tabel).
+  packageLocales: [],   // Opsional. Untuk nama multi-bahasa. Boleh [].
+  staticCounts: {       // Opsional. Angka agregat (mis. jumlah produk).
+    packages: 0,
+    sections: 0,
+  },
+}
+```
 
-### Kontrak data yang harus dikembalikan adapter
+> Nama field **harus** `bookings` dan `recent` walau domainmu bukan booking —
+> ini istilah internal modul. Isi datanya bebas (order, transaksi, reservasi, dll).
+
+**Output Adapter** (yang dirender oleh komponen):
 
 ```javascript
-// Format yang harus dikembalikan oleh adapter
 {
   stats: {
-    bookingsConfirm: number,  // jumlah transaksi confirmed
-    bookingsPending: number,  // jumlah transaksi pending
-    revenueConfirm: number,   // total pendapatan (dalam Rupiah, integer)
-    packages: number,         // jumlah produk/paket
-    sections: number,         // jumlah kategori/section (opsional, bisa 0)
-    avgRevenue: number,       // rata-rata pendapatan per transaksi
-    conversionRate: number,   // persentase konversi (0–100)
+    bookingsConfirm: number,  // angka untuk stat card (key bebas, asal cocok config)
+    revenueConfirm: number,
+    // ...tambahkan key lain sesuai kebutuhan
   },
   charts: {
-    dailyTrends: [            // untuk area chart tren harian
-      {
-        dateKey: "2026-05-01",          // format YYYY-MM-DD
-        label: "01 Mei",               // label untuk sumbu X chart
-        count: 5,                      // jumlah transaksi confirmed
-        revenue: 2500000,              // total revenue
-        pendingCount: 2,               // jumlah pending (untuk overlay)
-      }
+    dailyTrends: [            // area chart tren harian
+      { dateKey: "2026-05-01", label: "01 Mei", count: 5, revenue: 2500000, pendingCount: 2 }
     ],
-    statusDistribution: [     // untuk pie chart distribusi status
+    statusDistribution: [     // pie chart distribusi status
       { status: "confirmed", label: "Confirmed", count: 30 },
-      { status: "pending",   label: "Pending",   count: 10 },
     ],
-    audienceDistribution: [], // untuk pie chart distribusi audiens (boleh kosong [])
-    topPackages: [            // untuk bar chart produk/paket terlaris
+    audienceDistribution: [], // pie chart kedua (boleh kosong [])
+    topPackages: [            // bar chart terlaris (boleh kosong [])
       { packageId: "uuid", name: "Nama Produk", value: 10 },
     ],
   },
   table: {
-    recentBookings: [         // untuk tabel transaksi terbaru
+    recentBookings: [         // baris tabel transaksi terbaru
       {
         id: "uuid",
         createdAt: "2026-05-01T10:00:00Z",  // ISO string
         customerName: "Budi Santoso",
         packageName: "Nama Produk",
-        audienceLabel: "Domestic",          // label audiens (boleh "-")
-        totalIDR: 500000,                   // dalam Rupiah (integer)
+        audienceLabel: "Domestic",          // boleh "-"
+        totalIDR: 500000,                   // integer Rupiah
         status: "confirmed",                // lowercase
-        statusLabel: "Confirmed",           // label untuk ditampilkan
+        statusLabel: "Confirmed",
       }
     ],
   },
 }
 ```
 
-### Contoh adapter sederhana
+> Penting: `valueKey` di widget config (Bab 8) harus cocok dengan key di `stats`.
+> Contoh: jika config punya `valueKey: "revenueConfirm"`, adapter wajib
+> mengembalikan `stats.revenueConfirm`.
+
+---
+
+### 7.2 STUDI KASUS: Aplikasi Laundry (dari nol)
+
+Misalkan client punya 1 tabel Supabase bernama `laundry_orders`:
+
+| Kolom | Tipe | Contoh |
+|-------|------|--------|
+| `id` | uuid | `a1b2...` |
+| `created_at` | timestamptz | `2026-05-01T10:00:00Z` |
+| `customer_name` | text | `Budi Santoso` |
+| `total_price` | integer | `50000` |
+| `status` | text | `confirmed` / `pending` |
+| `service_type` | text | `Cuci Kering` |
+
+Target dashboard: 2 stat card (total order, total pendapatan), 2 chart
+(tren harian + distribusi status), dan 1 tabel order terbaru.
+
+---
+
+#### Langkah 1 — Tulis DATA SOURCE
+
+Buat file `src/datasources/laundryDataSource.js`. Tugasnya: query Supabase,
+kembalikan dalam bentuk `{ bookings, recent, staticCounts }`.
+
+```javascript
+// src/datasources/laundryDataSource.js
+export function createLaundrySupabaseSource(supabase) {
+  return {
+    // Dipanggil otomatis oleh useReusableDashboard setiap filter berubah.
+    // Parameter fromISO/toISO/statusScope sudah dihitung oleh modul.
+    async fetchDashboardSnapshot({ fromISO, toISO, statusScope }) {
+      // (a) Semua order dalam rentang tanggal → untuk chart & stats
+      const { data: orders = [] } = await supabase
+        .from("laundry_orders")
+        .select("id, created_at, customer_name, total_price, status, service_type")
+        .gte("created_at", fromISO)
+        .lte("created_at", toISO)
+        .order("created_at", { ascending: true });
+
+      // (b) 10 order terbaru → untuk tabel "Order Terbaru"
+      const recentQuery = supabase
+        .from("laundry_orders")
+        .select("id, created_at, customer_name, total_price, status, service_type")
+        .gte("created_at", fromISO)
+        .lte("created_at", toISO)
+        .order("created_at", { ascending: false })
+        .limit(10);
+
+      // Hormati filter status dari UI (confirmed/pending/all)
+      if (statusScope && statusScope !== "all") {
+        recentQuery.eq("status", statusScope);
+      }
+      const { data: recent = [] } = await recentQuery;
+
+      // (c) Angka agregat opsional, mis. jumlah jenis layanan
+      const { count: serviceCount } = await supabase
+        .from("services")
+        .select("*", { count: "exact", head: true });
+
+      // Kembalikan SESUAI KONTRAK (nama bookings & recent wajib)
+      return {
+        bookings: orders,
+        recent,
+        packageLocales: [],
+        staticCounts: { packages: serviceCount || 0, sections: 0 },
+      };
+    },
+
+    // OPSIONAL — aktifkan live update realtime. Hapus jika tak perlu.
+    subscribeLiveUpdate(onEvent) {
+      const channel = supabase
+        .channel("laundry-dashboard-live")
+        .on("postgres_changes",
+          { event: "*", schema: "public", table: "laundry_orders" }, onEvent)
+        .subscribe();
+      return () => supabase.removeChannel(channel);
+    },
+  };
+}
+```
+
+> Tips: kalau kamu **tidak** butuh realtime, cukup hapus fungsi
+> `subscribeLiveUpdate`. Badge "Live" otomatis tidak muncul.
+
+---
+
+#### Langkah 2 — Tulis ADAPTER
+
+Buat file `src/adapters/laundryAdapter.js`. Tugasnya: ubah `raw` dari data source
+menjadi `{ stats, charts, table }`. Pakai helper `toNumber` & `buildDayBuckets`
+dari modul agar tidak menulis ulang logika tanggal.
 
 ```javascript
 // src/adapters/laundryAdapter.js
 import { toNumber, buildDayBuckets } from "@rozaqi02/reusable-dashboard";
 
+// (1) State kosong — dipakai modul sebagai initial state & saat error.
+//     Strukturnya HARUS sama dengan output adaptLaundryData di bawah.
 export function createEmptyLaundryData() {
   return {
-    stats: { bookingsConfirm: 0, bookingsPending: 0, revenueConfirm: 0,
-             packages: 0, sections: 0, avgRevenue: 0, conversionRate: 0 },
+    stats: { bookingsConfirm: 0, revenueConfirm: 0 },
     charts: { dailyTrends: [], statusDistribution: [], audienceDistribution: [], topPackages: [] },
     table: { recentBookings: [] },
   };
 }
 
+// (2) Fungsi adapter utama.
 export function adaptLaundryData({ raw, filters, range, dateLocale, labels }) {
   if (!raw) return createEmptyLaundryData();
 
-  const orders = raw.bookings || [];   // nama field bisa disesuaikan di data source
+  const orders = raw.bookings || [];
   const recent = raw.recent || [];
 
-  // Bangun bucket harian
+  // Siapkan bucket harian kosong untuk chart tren (1 bucket = 1 hari)
   const dailyBuckets = buildDayBuckets(range.daysWindow, range.fromISO, dateLocale);
-  const dayLookup = new Map(dailyBuckets.map(b => [b.dateKey, b]));
+  const dayLookup = new Map(dailyBuckets.map((b) => [b.dateKey, b]));
 
-  let confirmed = 0, pending = 0, revenue = 0;
   const statusMap = new Map();
+  let confirmed = 0;
+  let revenue = 0;
 
-  orders.forEach(row => {
-    const status = (row.status || "pending").toLowerCase();
-    const amount = toNumber(row.total_price);  // sesuaikan nama kolom
-    const dayKey = row.created_at?.slice(0, 10);
+  // Loop semua order: hitung total & isi bucket harian
+  orders.forEach((row) => {
+    const status = String(row.status || "pending").toLowerCase();
+    const amount = toNumber(row.total_price);          // ← kolom DB kamu
+    const dayKey = String(row.created_at || "").slice(0, 10);
 
     statusMap.set(status, (statusMap.get(status) || 0) + 1);
 
@@ -473,98 +747,211 @@ export function adaptLaundryData({ raw, filters, range, dateLocale, labels }) {
       bucket.revenue += amount;
     }
 
-    if (status === "confirmed") { confirmed++; revenue += amount; }
-    else if (status === "pending") pending++;
+    if (status === "confirmed") { confirmed += 1; revenue += amount; }
   });
 
   return {
+    // stats: key di sini HARUS cocok dengan valueKey di widget config
     stats: {
       bookingsConfirm: confirmed,
-      bookingsPending: pending,
       revenueConfirm: revenue,
-      packages: toNumber(raw.staticCounts?.packages),
-      sections: 0,
-      avgRevenue: confirmed > 0 ? Math.round(revenue / confirmed) : 0,
-      conversionRate: confirmed + pending > 0 ? Math.round(confirmed / (confirmed + pending) * 100) : 0,
     },
     charts: {
       dailyTrends: dailyBuckets,
       statusDistribution: Array.from(statusMap.entries()).map(([status, count]) => ({
-        status, label: labels?.formatStatusLabel?.(status) || status, count
+        status,
+        label: labels?.formatStatusLabel?.(status) || status,
+        count,
       })),
-      audienceDistribution: [],
-      topPackages: [],
+      audienceDistribution: [],   // tidak dipakai laundry → kosong
+      topPackages: [],            // tidak dipakai laundry → kosong
     },
     table: {
-      recentBookings: recent.map(row => ({
-        id: row.id,
-        createdAt: row.created_at,
-        customerName: row.customer_name || "-",
-        packageName: row.service_type || "-",  // sesuaikan nama kolom
-        audienceLabel: "-",
-        totalIDR: toNumber(row.total_price),
-        status: (row.status || "pending").toLowerCase(),
-        statusLabel: labels?.formatStatusLabel?.(row.status) || row.status,
-      })),
+      recentBookings: recent.map((row) => {
+        const status = String(row.status || "pending").toLowerCase();
+        return {
+          id: row.id,
+          createdAt: row.created_at,
+          customerName: row.customer_name || "-",
+          packageName: row.service_type || "-",     // ← kolom DB kamu
+          audienceLabel: "-",
+          totalIDR: toNumber(row.total_price),
+          status,
+          statusLabel: labels?.formatStatusLabel?.(status) || status,
+        };
+      }),
     },
   };
 }
 ```
 
-### Contoh data source sederhana
+> Catatan: `audienceDistribution` dan `topPackages` boleh `[]` jika domainmu
+> tidak butuh. Lebih baik lagi: **jangan daftarkan** chart itu di widget config
+> (Langkah 3), supaya tidak tampil sama sekali.
 
-```javascript
-// src/datasources/laundryDataSource.js
-export function createLaundrySupabaseSource(supabase) {
-  return {
-    async fetchDashboardSnapshot({ fromISO, toISO, statusScope }) {
-      // Query utama
-      const { data: orders = [] } = await supabase
-        .from("laundry_orders")       // sesuaikan nama tabel
-        .select("id, created_at, customer_name, total_price, status, service_type")
-        .gte("created_at", fromISO)
-        .lte("created_at", toISO)
-        .order("created_at", { ascending: true });
+---
 
-      // Query recent (10 terbaru)
-      const recentQuery = supabase
-        .from("laundry_orders")
-        .select("id, created_at, customer_name, total_price, status, service_type")
-        .gte("created_at", fromISO)
-        .lte("created_at", toISO)
-        .order("created_at", { ascending: false })
-        .limit(10);
-      if (statusScope && statusScope !== "all") recentQuery.eq("status", statusScope);
-      const { data: recent = [] } = await recentQuery;
+#### Langkah 3 — Tulis WIDGET CONFIG
 
-      // Hitung jumlah layanan (opsional)
-      const { count: serviceCount } = await supabase
-        .from("services")
-        .select("*", { count: "exact", head: true });
+Buat file `src/config/laundryConfig.js`. Ini murni deklaratif — menentukan
+widget apa yang muncul. `valueKey` harus cocok dengan key `stats` dari adapter,
+dan `label` adalah key dari objek labels (Langkah 4).
 
-      return {
-        bookings: orders,             // wajib, nama harus "bookings"
-        recent,                       // wajib, nama harus "recent"
-        packageLocales: [],           // kosong jika tidak ada multi-bahasa
-        staticCounts: {
-          packages: serviceCount || 0,
-          sections: 0,
-        },
-      };
+```javascript
+// src/config/laundryConfig.js
+export const laundryConfig = {
+  id: "laundry.dashboard",
+  defaultFilters: {
+    statusScope: "confirmed",   // filter awal saat dibuka
+    daysPreset: 30,             // tampilkan 30 hari terakhir
+    sortPkgBy: "bookings",
+    sortPkgDir: "desc",
+  },
+  widgets: {
+    // 2 stat card → valueKey cocok dgn stats di adapter
+    stats: [
+      { id: "orders",  label: "confirmedBookings", icon: "TrendingUp",
+        valueKey: "bookingsConfirm", format: "number",   accentColor: "blue" },
+      { id: "revenue", label: "confirmedRevenue",  icon: "DollarSign",
+        valueKey: "revenueConfirm",  format: "currency", accentColor: "green" },
+    ],
+    // 2 chart → hanya yang ada datanya (tren & status)
+    charts: [
+      { id: "trend",  type: "dailyArea", label: "dailyTrends",        icon: "BarChart3" },
+      { id: "status", type: "statusPie", label: "statusDistribution", icon: "PieChart" },
+    ],
+    // 1 tabel → kolom mengacu ke field recentBookings dari adapter
+    table: {
+      id: "recentOrders",
+      label: "recentBookings",
+      icon: "Calendar",
+      emptyLabel: "noRecentBookings",
+      columns: [
+        { id: "date",     label: "date",     accessor: "createdAt",  type: "date" },
+        { id: "customer", label: "customer", accessor: "customerName" },
+        { id: "service",  label: "package",  accessor: "packageName" },
+        { id: "total",    label: "total",    accessor: "totalIDR",   type: "currency" },
+        { id: "status",   label: "status",   accessor: "statusLabel",
+          type: "statusBadge", statusAccessor: "status" },
+      ],
     },
+  },
+};
+```
 
-    // Opsional: subscribe ke perubahan realtime
-    subscribeLiveUpdate(onEvent) {
-      const channel = supabase
-        .channel("laundry-dashboard-live")
-        .on("postgres_changes", { event: "*", schema: "public", table: "laundry_orders" }, onEvent)
-        .subscribe();
-      return () => supabase.removeChannel(channel);
-    },
-  };
+> Detail tiap field config (tipe kolom, nama ikon, format) ada di
+> [Bab 8 — Konfigurasi Widget](#8-konfigurasi-widget).
+
+---
+
+#### Langkah 4 — Rangkai semuanya di halaman Dashboard
+
+Sekarang gabungkan ke-3 file di atas + objek labels, lalu serahkan ke
+`useReusableDashboard` dan render `ReusableDashboardView`.
+
+```jsx
+// src/pages/LaundryDashboard.jsx
+import React, { useMemo } from "react";
+import { supabase } from "../lib/supabaseClient";
+import {
+  ReusableDashboardView,
+  useReusableDashboard,
+} from "@rozaqi02/reusable-dashboard";
+
+// 3 file yang baru kamu buat:
+import { laundryConfig } from "../config/laundryConfig";
+import { createLaundrySupabaseSource } from "../datasources/laundryDataSource";
+import { adaptLaundryData, createEmptyLaundryData } from "../adapters/laundryAdapter";
+
+// Data source dibuat sekali di luar komponen (anti re-render)
+const source = createLaundrySupabaseSource(supabase);
+
+// Label UI — semua teks yang tampil. Sesuaikan bahasa/konteks bisnismu.
+const labels = {
+  title: "Dashboard Laundry",
+  refresh: "Refresh",
+  liveUpdate: "Live",
+  loadFailed: "Gagal memuat data.",
+  retry: "Coba Lagi",
+  allStatus: "Semua Status",
+  confirmedOnly: "Selesai",
+  pendingOnly: "Proses",
+  reset: "Reset",
+  confirmedBookings: "Total Order",
+  confirmedRevenue: "Total Pendapatan",
+  dailyTrends: "Tren Harian",
+  statusDistribution: "Distribusi Status",
+  recentBookings: "Order Terbaru",
+  noRecentBookings: "Belum ada order",
+  date: "Tanggal",
+  customer: "Pelanggan",
+  package: "Layanan",
+  total: "Total",
+  status: "Status",
+  bookingsMetric: "Order",
+  revenueMetric: "Pendapatan",
+  confirmedBookingMetric: "Order (Selesai)",
+  confirmedRevenueMetric: "Pendapatan (Selesai)",
+  dayLabel: (n) => `${n} hari`,
+  formatStatusLabel: (s) =>
+    ({ confirmed: "Selesai", pending: "Proses", cancelled: "Batal" })[s] || s,
+  formatAudienceLabel: (v) => v || "-",
+};
+
+export default function LaundryDashboard() {
+  const state = useReusableDashboard({
+    config: laundryConfig,                // ← Langkah 3
+    dataSource: source,                   // ← Langkah 1
+    adapter: adaptLaundryData,            // ← Langkah 2
+    createEmptyState: createEmptyLaundryData,  // ← Langkah 2
+    languageCode: "id",
+    dateLocale: "id-ID",
+    labels,
+  });
+
+  return (
+    <ReusableDashboardView
+      config={laundryConfig}
+      labels={labels}
+      loading={state.loading}
+      error={state.error}
+      filters={state.filters}
+      onFilterChange={state.updateFilter}
+      onResetFilters={state.resetFilters}
+      onRefresh={state.refresh}
+      data={state.data}
+      dateLocale="id-ID"
+      liveUpdateEnabled={state.liveUpdateEnabled}
+    />
+  );
 }
 ```
 
+Selesai. Buka halaman tersebut → dashboard laundry tampil lengkap dengan data
+dari Supabase, filter tanggal, search, sort, dan pagination — semua sudah
+ditangani modul.
+
+---
+
+### 7.3 Checklist & troubleshooting domain baru
+
+| Gejala | Penyebab umum | Solusi |
+|--------|---------------|--------|
+| Stat card menampilkan `0` terus | `valueKey` di config tidak cocok dengan key `stats` adapter | Samakan nama, mis. `valueKey: "revenueConfirm"` ↔ `stats.revenueConfirm` |
+| Chart kosong | Data source tidak mengembalikan `bookings`, atau status bukan `"confirmed"` | Pastikan field bernama `bookings` & status lowercase |
+| Tabel kosong padahal ada data | Data source tidak mengembalikan `recent` | Tambahkan query `recent` (10 terbaru) |
+| Error "is not a function" | Lupa pasang `createEmptyState` | Wajib kirim `createEmptyXxxData` ke hook |
+| Label tampil sebagai key mentah | Key di config (`label`) tidak ada di objek `labels` | Tambahkan key tersebut di objek labels |
+| Badge "Live" tidak muncul | `subscribeLiveUpdate` tidak ada / Realtime belum aktif | Tambahkan fungsi + aktifkan Realtime di Supabase |
+
+Checklist final sebelum rilis ke client:
+- [ ] Data source mengembalikan `{ bookings, recent }` (nama persis).
+- [ ] Adapter mengembalikan `{ stats, charts, table }` lengkap.
+- [ ] `createEmptyXxxData` punya struktur sama dengan output adapter.
+- [ ] Semua `valueKey` di config ada di `stats`.
+- [ ] Semua `label`/`emptyLabel` di config ada di objek `labels`.
+- [ ] RLS Supabase mengizinkan `SELECT` untuk role `anon` (lihat [Bab 6](#6-setup-database-supabase)).
+
 ---
 
 ## 8. Konfigurasi Widget
@@ -762,6 +1149,20 @@ function Dashboard() {
 | `cidikaWidgetConfig` | Object | Config dashboard Cidika Travel |
 | `tokoSepatuWidgetConfig` | Object | Config dashboard Toko Sepatu |
 | `dummyUmkmWidgetConfig` | Object | Config dashboard UMKM generik |
+| `createDashboardConfig(options)` | Function | Factory: kemas semua config jadi 1 objek (v1.1.3+) |
+| `validateDashboardConfig(cfg)` | Function | Validasi config, kembalikan `{ valid, issues }` (v1.1.3+) |
+
+**`createDashboardConfig(options)` — parameter:**
+
+| Parameter | Tipe | Wajib | Keterangan |
+|-----------|------|-------|------------|
+| `widgetConfig` | Object | ✅ | Konfigurasi widget deklaratif |
+| `dataSource` | Object | ✅ | Hasil `createXxxSupabaseSource(supabase)` |
+| `adapter` | Function | ✅ | Fungsi `adaptXxxData` |
+| `createEmptyState` | Function | ✅ | Fungsi `createEmptyXxxData` |
+| `labels` | Object | — | Objek label UI (bisa di-override saat render) |
+| `languageCode` | string | — | Default `"id"` |
+| `dateLocale` | string | — | Default `"id-ID"` |
 
 ### Data Source
 
@@ -812,6 +1213,7 @@ state.range             // { fromISO, toISO, daysWindow }
 | Komponen | Deskripsi |
 |----------|-----------|
 | `ReusableDashboardView` | Halaman dashboard lengkap — gunakan ini untuk integrasi cepat |
+| `SetupWizard` | Pop-up wizard panduan konfigurasi interaktif (v1.1.3+) |
 | `StatCard` | Kartu metrik dengan warna aksen |
 | `ChartCard` | Kartu grafik (area/pie/bar) |
 | `DataTable` | Tabel dengan search, sort, pagination |
@@ -828,6 +1230,24 @@ state.range             // { fromISO, toISO, daysWindow }
 | `SidebarNavigation` | Navigasi sidebar |
 | `TopbarHeader` | Header atas |
 
+**Props `ReusableDashboardView` (lengkap):**
+
+| Prop | Tipe | Wajib | Keterangan |
+|------|------|-------|------------|
+| `config` | Object | ✅ | Widget configuration |
+| `labels` | Object | ✅ | Objek label UI |
+| `loading` | boolean | — | Status loading data |
+| `error` | string | — | Pesan error |
+| `filters` | Object | — | State filter aktif |
+| `onFilterChange` | Function | ✅ | `(field, value) => void` |
+| `onResetFilters` | Function | ✅ | `() => void` |
+| `onRefresh` | Function | ✅ | `() => void` |
+| `data` | Object | — | Data `{ stats, charts, table }` |
+| `dateLocale` | string | — | Default `"id-ID"` |
+| `liveUpdateEnabled` | boolean | — | Badge "Live" aktif |
+| `supabase` | Object | — | Supabase client — aktifkan fitur baca tabel di wizard (v1.1.3+) |
+| `dashboardConfig` | Object | — | Hasil `createDashboardConfig()` — aktifkan validasi otomatis (v1.1.3+) |
+
 ### Utility
 
 | Function | Deskripsi |
@@ -845,7 +1265,91 @@ state.range             // { fromISO, toISO, daysWindow }
 
 ---
 
-## 11. Pengembangan & Kontribusi
+## 11. Setup Wizard — Panduan Konfigurasi Interaktif
+
+Mulai versi **1.1.3**, modul menyertakan **Setup Wizard**: pop-up panduan interaktif yang
+muncul **otomatis** saat `ReusableDashboardView` mendeteksi konfigurasi belum lengkap.
+
+Ini menjawab kebutuhan: *"developer baru yang belum pernah pakai modul ini tahu harus
+mulai dari mana tanpa harus baca README dari awal."*
+
+### Cara kerja
+
+Wizard aktif ketika salah satu kondisi terpenuhi:
+- Prop `dashboardConfig` (dari `createDashboardConfig`) punya `_meta.isValid === false`
+- Prop `config`, `labels`, atau `labels.formatStatusLabel` tidak ditemukan
+
+Wizard **tidak** muncul jika semua konfigurasi sudah valid.
+
+### Fitur wizard
+
+**Step 0 — Overview:**
+- Checklist masalah yang ditemukan (mis. `"adapter belum diisi"`)
+- Diagram alur konfigurasi: Data Source → Adapter → Widget Config
+
+**Step 1 — Data Source:**
+- Contoh kode `fetchDashboardSnapshot` yang siap di-copy
+- Tombol **"Baca tabel Supabase langsung"** — membaca daftar tabel dari project
+  Supabase kamu secara realtime via `information_schema.tables`
+
+**Step 2 — Adapter:**
+- Contoh kode `adaptMyData` dengan `buildDayBuckets` + `toNumber`
+- Penjelasan bahwa key `stats` harus cocok dengan `valueKey` di widget config
+
+**Step 3 — Widget Config & Rangkaian Akhir:**
+- Contoh kode lengkap dengan `createDashboardConfig` dari langkah 1–3
+
+### Cara mengaktifkan fitur baca tabel Supabase
+
+Tambahkan prop `supabase` ke `ReusableDashboardView`:
+
+```jsx
+<ReusableDashboardView
+  config={dashboardConfig.config}
+  labels={labels}
+  // ... props lain
+  supabase={supabase}               // ← aktifkan fitur baca tabel
+  dashboardConfig={dashboardConfig} // ← aktifkan validasi otomatis
+/>
+```
+
+Saat wizard terbuka di Step 1, pengguna bisa klik tombol untuk melihat
+daftar tabel yang tersedia di project Supabase mereka:
+
+```
+Tabel ditemukan (4):
+  bookings   packages   package_locales   page_sections
+```
+
+> Fitur ini membutuhkan RLS Supabase mengizinkan `SELECT` pada
+> `information_schema.tables` untuk role `anon`, atau fallback ke RPC `get_tables`.
+> Jika tidak bisa diakses, wizard tetap berfungsi — hanya tombol baca tabel yang
+> menampilkan pesan error.
+
+### Menggunakan wizard tanpa `createDashboardConfig`
+
+Wizard juga bisa dipakai standalone (misalnya saat testing atau demo):
+
+```jsx
+import { SetupWizard } from "@rozaqi02/reusable-dashboard";
+
+// Tampilkan wizard dengan isu kustom
+<SetupWizard
+  issues={["Widget config belum diisi", "Data source tidak ditemukan"]}
+  supabase={supabase}
+  onDismiss={() => console.log("wizard ditutup")}
+/>
+```
+
+### Menutup wizard
+
+Klik tombol **"Lanjutkan tanpa wizard"** atau **"Tutup & lanjutkan ✓"** di Step 3.
+Wizard tidak muncul lagi selama sesi berlangsung (state `wizardDismissed` disimpan
+di level komponen).
+
+---
+
+## 12. Pengembangan & Kontribusi
 
 ```bash
 # Clone repository
@@ -861,13 +1365,48 @@ npm run build        # Output ke dist/
 # Test
 npm test             # Jest + React Testing Library
 npm test -- --coverage  # Lihat code coverage
+```
+
+### Cara Publish Versi Baru ke npm
+
+Modul ini publik di npm: `@rozaqi02/reusable-dashboard`. Setiap kali kode modul
+berubah, kamu wajib publish versi baru agar perubahan sampai ke client.
+
+```bash
+# 1. Pastikan sudah login (sekali saja per device)
+npm login            # buka browser untuk autentikasi
+npm whoami           # verifikasi → harus muncul "rozaqi02"
 
-# Publish versi baru
-npm version patch    # 1.0.0 → 1.0.1
-npm version minor    # 1.0.0 → 1.1.0
-npm publish          # Build otomatis sebelum publish
+# 2. Naikkan versi (pilih salah satu sesuai jenis perubahan)
+npm version patch    # 1.1.2 → 1.1.3  (bug fix / perbaikan kecil)
+npm version minor    # 1.1.2 → 1.2.0  (fitur baru, tanpa breaking change)
+npm version major    # 1.1.2 → 2.0.0  (breaking change)
+
+# 3. Publish (build otomatis jalan dulu lewat prepublishOnly)
+npm publish          # akan meminta OTP (One-Time Password)
 ```
 
+> **Catatan OTP:** karena akun npm kamu mengaktifkan 2FA, `npm publish` akan
+> meminta one-time password. Masukkan kode dari aplikasi authenticator kamu
+> (atau gunakan `npm publish --otp=123456`). Langkah ini **harus dijalankan
+> manual di terminal kamu** — tidak bisa diotomasi.
+
+> **Publish ≠ git push.** `npm publish` hanya mengunggah isi folder `dist/`
+> (lihat field `files` di `package.json`) ke registry npm. Tidak bergantung pada
+> commit/push git terakhir. Jadi kamu tidak perlu push ke GitHub dulu agar
+> bisa publish — keduanya independen. (Tetap disarankan commit & push agar
+> source code di GitHub sinkron dengan versi yang dirilis.)
+
+### Update Modul di Project Client
+
+Setelah versi baru terbit, di setiap project yang memakai modul:
+
+```bash
+npm install @rozaqi02/reusable-dashboard@latest
+```
+
+Lalu restart dev server (`npm start` / `npm run dev`) agar perubahan termuat.
+
 ---
 
 ## License