@rozaqi02/reusable-dashboard 1.1.3 → 1.1.4

package/README.md

@@ -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)
 
 ---
 
@@ -313,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:
@@ -1053,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
 
@@ -1103,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 |
@@ -1119,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 |
@@ -1136,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