@rozaqi02/reusable-dashboard 1.0.1 → 1.1.2

package/README.md

@@ -1,85 +1,181 @@
 # @rozaqi02/reusable-dashboard
 
-Modul dashboard admin reusable untuk UMKM berbasis React + Atomic Design + Supabase.
-Mendukung berbagai domain bisnis (travel, toko online, dll.) tanpa mengubah komponen inti —
-cukup definisikan widget configuration dan data adapter yang sesuai.
+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.0.0-blue)](./CHANGELOG.md)
-[![license](https://img.shields.io/badge/license-Proprietary-red)](./LICENSE)
-[![build](https://img.shields.io/badge/build-passing-brightgreen)](#)
+[![version](https://img.shields.io/badge/version-1.1.1-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)
 
 ---
 
-## 📦 Installation
+## Daftar Isi
+
+1. [Instalasi](#1-instalasi)
+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)
+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)
+
+---
+
+## 1. Instalasi
 
 ```bash
 npm install @rozaqi02/reusable-dashboard
+npm install recharts @supabase/supabase-js
 ```
 
-## ✅ Prerequisites
+> **Catatan:** CSS sudah otomatis terbundle di dalam paket ini (`dist/index.css`).
+> Tidak perlu menginstall atau mengkonfigurasi Tailwind CSS.
 
-- **Node.js** >= 16.x
-- **React** >= 18.0.0
-- **Supabase** account dan project yang sudah dibuat
-- **Tailwind CSS** >= 3.0 dikonfigurasi pada project konsumen
+---
 
-## 🔧 Peer Dependencies
+## 2. Prasyarat Teknis
 
-Install peer dependencies yang dibutuhkan:
+| Prasyarat | Versi Minimum | Keterangan |
+|-----------|---------------|------------|
+| Node.js | 16.x | Runtime JavaScript |
+| React | 18.0.0 | UI framework |
+| 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) |
 
-```bash
-npm install react react-dom recharts @supabase/supabase-js lucide-react prop-types tailwindcss
-```
+Modul ini dirancang khusus untuk aplikasi React yang menggunakan Supabase sebagai backend.
+Belum mendukung backend lain (Firebase, REST API, GraphQL) tanpa menulis data source sendiri.
 
-> **Tailwind CSS wajib** karena komponen menggunakan utility classes Tailwind untuk styling.
-> Pastikan Tailwind sudah dikonfigurasi di project kamu (lihat [panduan Tailwind](https://tailwindcss.com/docs/installation)).
+---
+
+## 3. Preset yang Tersedia
+
+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 |
+
+Setiap preset sudah termasuk: konfigurasi widget, data adapter, dan data source Supabase.
 
 ---
 
-## 🚀 Quick Start
+## 4. Quick Start — Toko Sepatu
 
-### Step 1: Setup Supabase Client
+Ini adalah contoh paling lengkap. Ikuti step by step dari nol.
 
-Buat file `src/lib/supabaseClient.js`:
+### Step 1 — Setup Supabase
 
-```javascript
-import { createClient } from '@supabase/supabase-js';
+**A. Buat project Supabase** di [app.supabase.com](https://app.supabase.com)
 
-export const supabase = createClient(
-  import.meta.env.VITE_SUPABASE_URL,      // Vite
-  import.meta.env.VITE_SUPABASE_ANON_KEY  // Vite
-  // atau process.env.REACT_APP_SUPABASE_URL jika pakai Create React App
+**B. Jalankan SQL schema** berikut di Supabase SQL Editor
+(Settings → SQL Editor → New Query):
+
+```sql
+-- Tabel pelanggan
+CREATE TABLE public.customers (
+  id uuid NOT NULL DEFAULT gen_random_uuid(),
+  name text NOT NULL,
+  email text,
+  phone text,
+  city text,
+  created_at timestamp with time zone DEFAULT now(),
+  CONSTRAINT customers_pkey PRIMARY KEY (id)
 );
-```
 
-Buat file `.env` di root project:
+-- Tabel produk
+CREATE TABLE public.products (
+  id uuid NOT NULL DEFAULT gen_random_uuid(),
+  name text NOT NULL,
+  brand text NOT NULL DEFAULT 'Generic',
+  category text NOT NULL DEFAULT 'sneakers',
+  price_idr integer NOT NULL,
+  stock integer NOT NULL DEFAULT 0,
+  is_active boolean NOT NULL DEFAULT true,
+  created_at timestamp with time zone DEFAULT now(),
+  CONSTRAINT products_pkey PRIMARY KEY (id)
+);
 
-```env
-# Vite
-VITE_SUPABASE_URL=https://your-project.supabase.co
-VITE_SUPABASE_ANON_KEY=your-anon-key
+-- Tabel pesanan
+CREATE TABLE public.orders (
+  id uuid NOT NULL DEFAULT gen_random_uuid(),
+  customer_id uuid NOT NULL,
+  total_amount integer NOT NULL,
+  status text NOT NULL DEFAULT 'pending',
+  created_at timestamp with time zone DEFAULT now(),
+  CONSTRAINT orders_pkey PRIMARY KEY (id),
+  CONSTRAINT orders_customer_id_fkey FOREIGN KEY (customer_id)
+    REFERENCES public.customers(id)
+);
+
+-- Tabel detail item pesanan
+CREATE TABLE public.order_items (
+  id bigint GENERATED ALWAYS AS IDENTITY,
+  order_id uuid NOT NULL,
+  product_id uuid NOT NULL,
+  qty integer NOT NULL DEFAULT 1,
+  price_idr integer NOT NULL,
+  subtotal integer NOT NULL,
+  CONSTRAINT order_items_pkey PRIMARY KEY (id),
+  CONSTRAINT order_items_order_id_fkey FOREIGN KEY (order_id)
+    REFERENCES public.orders(id),
+  CONSTRAINT order_items_product_id_fkey FOREIGN KEY (product_id)
+    REFERENCES public.products(id)
+);
 
-# Create React App
-# REACT_APP_SUPABASE_URL=https://your-project.supabase.co
-# REACT_APP_SUPABASE_ANON_KEY=your-anon-key
+-- Aktifkan Realtime (untuk fitur live update)
+ALTER PUBLICATION supabase_realtime ADD TABLE public.orders;
+ALTER PUBLICATION supabase_realtime ADD TABLE public.products;
+ALTER PUBLICATION supabase_realtime ADD TABLE public.customers;
 ```
 
-### Step 2: Setup Database Schema
+**C. Isi data contoh** (opsional, untuk testing):
 
-Jalankan SQL schema di Supabase SQL Editor sesuai domain bisnis:
+File seed data lengkap tersedia di:
+`examples/toko-sepatu-example/seed-data.sql` dalam repositori ini.
 
-| Domain | File SQL |
-|--------|----------|
-| Cidika Travel | `examples/cidika-travel-example/supabase-schema.sql` |
-| Toko Sepatu | `examples/toko-sepatu-example/supabase-schema.sql` |
+**D. Aktifkan Realtime** di Supabase Dashboard:
+Database → Replication → centang tabel `orders`, `products`, `customers`.
 
-### Step 3: Implementasi Dashboard
+### Step 2 — Buat Supabase client
 
-Contoh menggunakan preset **Toko Sepatu**:
+```js
+// src/lib/supabaseClient.js
+import { createClient } from '@supabase/supabase-js';
+
+export const supabase = createClient(
+  process.env.REACT_APP_SUPABASE_URL,    // CRA
+  process.env.REACT_APP_SUPABASE_ANON_KEY
+  // Jika pakai Vite: import.meta.env.VITE_SUPABASE_URL
+);
+```
+
+```env
+# .env (di root project)
+REACT_APP_SUPABASE_URL=https://xxxxxx.supabase.co
+REACT_APP_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+
+# Jika pakai Vite:
+# VITE_SUPABASE_URL=https://xxxxxx.supabase.co
+# VITE_SUPABASE_ANON_KEY=eyJ...
+```
+
+Nilai URL dan ANON KEY didapat dari Supabase Dashboard:
+**Settings → API → Project URL & anon key**.
+
+### Step 3 — Implementasi halaman Dashboard
 
 ```jsx
+// src/pages/Dashboard.jsx
 import React, { useMemo } from "react";
-import { supabase } from "./lib/supabaseClient";
+import { supabase } from "../lib/supabaseClient";
 import {
   ReusableDashboardView,
   tokoSepatuWidgetConfig,
@@ -89,12 +185,13 @@ import {
   useReusableDashboard,
 } from "@rozaqi02/reusable-dashboard";
 
-// Inisialisasi data source satu kali di luar komponen
+// Inisialisasi data source — dibuat sekali di luar komponen
 const source = createTokoSepatuSupabaseSource(supabase);
 
-// Label minimal tanpa i18n — override semua key yang diperlukan
+// Label UI dalam Bahasa Indonesia
+// Ganti nilai-nilai ini sesuai bahasa/konteks bisnis kamu
 const labels = {
-  title: "Dashboard Toko Sepatu",
+  title: "Dashboard Toko Saya",
   refresh: "Refresh",
   liveUpdate: "Live",
   loadFailed: "Gagal memuat data.",
@@ -104,10 +201,12 @@ const labels = {
   allStatus: "Semua Status",
   showPendingOverlay: "Tampilkan pending",
   allAudience: "Semua",
+  audienceDomestic: "Domestic",
+  audienceForeign: "Foreign",
   customDate: "Kustom",
   reset: "Reset",
   topSort: "Urutkan",
-  sortBookings: "Qty",
+  sortBookings: "Qty Terjual",
   sortRevenue: "Revenue",
   sortDesc: "Turun",
   sortAsc: "Naik",
@@ -123,6 +222,7 @@ const labels = {
   date: "Tanggal",
   customer: "Pelanggan",
   package: "Produk",
+  audience: "Audiens",
   total: "Total",
   status: "Status",
   noRecentBookings: "Belum ada pesanan",
@@ -132,7 +232,7 @@ const labels = {
   confirmedBookingMetric: "Pesanan (Confirmed)",
   confirmedRevenueMetric: "Pendapatan (Confirmed)",
   unknownAudience: "Unknown",
-  dayLabel: (count) => `${count} hari`,
+  dayLabel: (n) => `${n} hari`,
   formatStatusLabel: (s) => ({ confirmed: "Confirmed", pending: "Pending", cancelled: "Cancelled" })[s] || s,
   formatAudienceLabel: (v) => v || "Unknown",
 };
@@ -166,91 +266,336 @@ export default function Dashboard() {
 }
 ```
 
-> **Menggunakan react-i18next?** Gunakan `createDashboardLabels(t)` dari export modul
-> sebagai pengganti objek labels di atas. Lihat [bagian i18n](#-label--i18n).
-
-### Step 4: Jalankan Aplikasi
+### Step 4 — Jalankan
 
 ```bash
-npm run dev   # Vite
+npm start   # Create React App
 # atau
-npm start     # Create React App
+npm run dev  # Vite
 ```
 
+Buka browser → dashboard tampil dengan data dari Supabase.
+
 ---
 
-## 📚 Available Presets
+## 5. Quick Start — Cidika Travel
 
-### 1. Cidika Travel (Travel Agency)
+Ganti hanya 4 baris dari contoh Toko Sepatu di atas:
 
-```javascript
+```jsx
 import {
-  cidikaWidgetConfig,
-  createCidikaSupabaseSource,
-  adaptCidikaDashboardData,
-  createEmptyDashboardData,
+  ReusableDashboardView,
+  cidikaWidgetConfig,              // ← ganti ini
+  createCidikaSupabaseSource,      // ← ganti ini
+  adaptCidikaDashboardData,        // ← ganti ini
+  createEmptyDashboardData,        // ← ganti ini
+  createDashboardLabels,
+  useReusableDashboard,
 } from "@rozaqi02/reusable-dashboard";
 
+// Jika pakai react-i18next:
+const { t } = useTranslation();
+const labels = useMemo(() => createDashboardLabels(t), [t]);
+
+// Jika tidak pakai i18n, gunakan objek labels manual seperti contoh Toko Sepatu
+
 const source = createCidikaSupabaseSource(supabase);
+
+const state = useReusableDashboard({
+  config: cidikaWidgetConfig,
+  dataSource: source,
+  adapter: adaptCidikaDashboardData,
+  createEmptyState: createEmptyDashboardData,
+  languageCode: "id",
+  dateLocale: "id-ID",
+  labels,
+});
 ```
 
-Tabel Supabase yang dibutuhkan: `bookings`, `packages`, `package_locales`, `page_sections`
+**Tabel Supabase yang dibutuhkan untuk Cidika Travel:**
 
-### 2. Toko Sepatu (Online Shop)
+```sql
+-- Tabel utama
+bookings (id, created_at, total_idr, status, package_id, audience, customer_name)
+packages (id, slug, price, is_active)
+package_locales (package_id, lang, title)  -- untuk nama paket multi-bahasa
+page_sections (id, page_id, type, order)   -- untuk menghitung jumlah section
+```
 
-```javascript
-import {
-  tokoSepatuWidgetConfig,
-  createTokoSepatuSupabaseSource,
-  adaptTokoSepatuData,
-  createEmptyTokoSepatuData,
-} from "@rozaqi02/reusable-dashboard";
+---
 
-const source = createTokoSepatuSupabaseSource(supabase);
+## 6. Setup Database Supabase
+
+### Cara mendapatkan URL dan API Key
+
+1. Login ke [app.supabase.com](https://app.supabase.com)
+2. Buka project kamu
+3. Klik **Settings** (ikon gear) di sidebar kiri
+4. Klik **API**
+5. Salin:
+   - **Project URL** → `REACT_APP_SUPABASE_URL`
+   - **anon public** key → `REACT_APP_SUPABASE_ANON_KEY`
+
+### Mengaktifkan Realtime (wajib untuk live update)
+
+1. Di Supabase Dashboard, klik **Database** di sidebar
+2. Klik **Replication**
+3. Di bagian **Source**, aktifkan toggle untuk tabel yang ingin di-listen
+4. Atau jalankan SQL berikut:
+
+```sql
+-- Untuk Toko Sepatu:
+ALTER PUBLICATION supabase_realtime ADD TABLE public.orders;
+ALTER PUBLICATION supabase_realtime ADD TABLE public.products;
+
+-- Untuk Cidika Travel:
+ALTER PUBLICATION supabase_realtime ADD TABLE public.bookings;
+ALTER PUBLICATION supabase_realtime ADD TABLE public.packages;
 ```
 
-Tabel Supabase yang dibutuhkan: `orders`, `order_items`, `products`, `customers`
+### Row Level Security (RLS)
 
-### 3. Dummy UMKM (Generic)
+Jika dashboard tidak menampilkan data padahal data sudah ada, kemungkinan
+RLS (Row Level Security) memblokir query. Solusi sementara untuk development:
 
-```javascript
-import {
-  dummyUmkmWidgetConfig,
-  adaptDummyUmkmData,
-  createEmptyDummyUmkmData,
-} from "@rozaqi02/reusable-dashboard";
+```sql
+-- PERHATIAN: Hanya untuk development. Jangan gunakan di production
+-- tanpa menambahkan policy yang benar.
+ALTER TABLE public.orders DISABLE ROW LEVEL SECURITY;
+ALTER TABLE public.customers DISABLE ROW LEVEL SECURITY;
+ALTER TABLE public.products DISABLE ROW LEVEL SECURITY;
 ```
 
-> Dummy UMKM tidak memiliki data source khusus.
-> Gunakan data source Toko Sepatu atau buat sendiri.
+Untuk production, tambahkan policy yang sesuai:
+
+```sql
+-- Contoh policy: izinkan semua operasi SELECT untuk role anon
+CREATE POLICY "Allow read for anon" ON public.orders
+  FOR SELECT TO anon USING (true);
+```
 
 ---
 
-## 🎨 Customization
+## 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.
+
+### Kontrak data yang harus dikembalikan adapter
+
+```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)
+  },
+  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)
+      }
+    ],
+    statusDistribution: [     // untuk 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
+      { packageId: "uuid", name: "Nama Produk", value: 10 },
+    ],
+  },
+  table: {
+    recentBookings: [         // untuk 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)
+        status: "confirmed",                // lowercase
+        statusLabel: "Confirmed",           // label untuk ditampilkan
+      }
+    ],
+  },
+}
+```
+
+### Contoh adapter sederhana
+
+```javascript
+// src/adapters/laundryAdapter.js
+import { toNumber, buildDayBuckets } from "@rozaqi02/reusable-dashboard";
+
+export function createEmptyLaundryData() {
+  return {
+    stats: { bookingsConfirm: 0, bookingsPending: 0, revenueConfirm: 0,
+             packages: 0, sections: 0, avgRevenue: 0, conversionRate: 0 },
+    charts: { dailyTrends: [], statusDistribution: [], audienceDistribution: [], topPackages: [] },
+    table: { recentBookings: [] },
+  };
+}
+
+export function adaptLaundryData({ raw, filters, range, dateLocale, labels }) {
+  if (!raw) return createEmptyLaundryData();
+
+  const orders = raw.bookings || [];   // nama field bisa disesuaikan di data source
+  const recent = raw.recent || [];
+
+  // Bangun bucket harian
+  const dailyBuckets = buildDayBuckets(range.daysWindow, range.fromISO, dateLocale);
+  const dayLookup = new Map(dailyBuckets.map(b => [b.dateKey, b]));
+
+  let confirmed = 0, pending = 0, revenue = 0;
+  const statusMap = new Map();
+
+  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);
+
+    statusMap.set(status, (statusMap.get(status) || 0) + 1);
+
+    const bucket = dayLookup.get(dayKey);
+    if (bucket && status === "confirmed") {
+      bucket.count += 1;
+      bucket.revenue += amount;
+    }
+
+    if (status === "confirmed") { confirmed++; revenue += amount; }
+    else if (status === "pending") pending++;
+  });
+
+  return {
+    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
+      })),
+      audienceDistribution: [],
+      topPackages: [],
+    },
+    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,
+      })),
+    },
+  };
+}
+```
+
+### Contoh data source sederhana
+
+```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;
+
+      // Hitung jumlah layanan (opsional)
+      const { count: serviceCount } = await supabase
+        .from("services")
+        .select("*", { count: "exact", head: true });
+
+      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,
+        },
+      };
+    },
 
-### Custom Widget Configuration
+    // 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);
+    },
+  };
+}
+```
+
+---
 
-Struktur konfigurasi yang benar (sesuai kontrak API modul):
+## 8. Konfigurasi Widget
+
+Widget configuration menentukan apa yang ditampilkan di dashboard.
+Kamu bisa gunakan preset yang ada atau buat konfigurasi baru.
 
 ```javascript
 export const myConfig = {
-  id: "my-business.dashboard",
+  id: "my.dashboard",
+
+  // Filter default saat pertama kali dibuka
   defaultFilters: {
-    statusScope: "all",      // "confirmed" | "pending" | "all"
-    daysPreset: 30,          // preset hari (7 | 30 | 90 | 0 untuk kustom)
-    sortPkgBy: "revenue",    // "bookings" | "revenue"
-    sortPkgDir: "desc",      // "asc" | "desc"
-    includePendingOverlay: false,
-    audience: "",
+    statusScope: "confirmed",          // "confirmed" | "pending" | "all"
+    includePendingOverlay: false,      // tampilkan overlay pending di chart?
+    audience: "",                      // "" | "domestic" | "foreign"
+    daysPreset: 30,                    // 7 | 30 | 90 | 0 (0 = custom range)
+    sortPkgBy: "revenue",              // "bookings" | "revenue"
+    sortPkgDir: "desc",                // "desc" | "asc"
   },
+
   widgets: {
+    // Stat cards (1–4 kartu)
     stats: [
       {
         id: "totalOrders",
-        label: "confirmedBookings",  // key pada objek labels
-        icon: "TrendingUp",          // nama ikon dari Lucide React
-        valueKey: "bookingsConfirm", // key pada data.stats dari adapter
-        format: "number",            // "number" | "currency" | "percent"
+        label: "confirmedBookings",     // key dari objek labels
+        icon: "TrendingUp",             // nama ikon Lucide
+        valueKey: "bookingsConfirm",    // key dari data.stats yang dikembalikan adapter
+        format: "number",              // "number" | "currency" | "percent"
+        accentColor: "blue",           // "blue" | "green" | "violet" | "orange" | "sky" | "rose"
       },
       {
         id: "totalRevenue",
@@ -258,34 +603,41 @@ export const myConfig = {
         icon: "DollarSign",
         valueKey: "revenueConfirm",
         format: "currency",
+        accentColor: "green",
       },
     ],
+
+    // Chart cards (1–4 chart)
     charts: [
       {
-        id: "dailyTrends",
-        type: "dailyArea",       // "dailyArea" | "statusPie" | "audiencePie" | "topPackagesBar"
-        label: "dailyTrends",
+        id: "trendHarian",
+        type: "dailyArea",             // "dailyArea" | "statusPie" | "audiencePie" | "topPackagesBar"
+        label: "dailyTrends",          // key dari objek labels
         icon: "BarChart3",
       },
       {
-        id: "statusDist",
+        id: "distribusiStatus",
         type: "statusPie",
         label: "statusDistribution",
         icon: "PieChart",
       },
     ],
+
+    // Tabel (hanya 1)
     table: {
       id: "recentOrders",
-      label: "recentBookings",
+      label: "recentBookings",         // key dari objek labels
       icon: "Calendar",
-      emptyLabel: "noRecentBookings",
+      emptyLabel: "noRecentBookings",  // key dari objek labels, untuk empty state
       columns: [
         { id: "date",     label: "date",     accessor: "createdAt",    type: "date" },
         { id: "customer", label: "customer", accessor: "customerName" },
+        { id: "product",  label: "package",  accessor: "packageName" },
         { id: "total",    label: "total",    accessor: "totalIDR",     type: "currency" },
         {
           id: "status", label: "status", accessor: "statusLabel",
-          type: "statusBadge", statusAccessor: "status",
+          type: "statusBadge",
+          statusAccessor: "status",   // kolom yang berisi status lowercase (confirmed/pending/cancelled)
         },
       ],
     },
@@ -293,97 +645,97 @@ export const myConfig = {
 };
 ```
 
-### Custom Data Source
+**Tipe kolom tabel:**
+| `type` | Format Output |
+|--------|---------------|
+| `date` | Diformat dengan `dateLocale` (contoh: "01 Mei 2026") |
+| `currency` | Diformat dengan prefix "Rp" dan titik ribuan |
+| `statusBadge` | Badge berwarna sesuai status |
+| _(tanpa type)_ | Ditampilkan apa adanya (string) |
 
-Kontrak yang harus diimplementasikan:
-
-```javascript
-export function createMySupabaseSource(supabase) {
-  return {
-    // Wajib: mengambil snapshot data dashboard
-    async fetchDashboardSnapshot({ fromISO, toISO, audience, statusScope, languageCode }) {
-      const { data: orders, error } = await supabase
-        .from("orders")
-        .select("id, created_at, total_amount, status, customer_id")
-        .gte("created_at", fromISO)
-        .lte("created_at", toISO);
+**Nama ikon yang tersedia:**
+`TrendingUp`, `TrendingDown`, `DollarSign`, `Users`, `PieChart`, `BarChart3`,
+`Calendar`, `RotateCcw`, `Search`, `ChevronLeft`, `ChevronRight`, `ArrowUp`,
+`ArrowDown`, `AlertCircle`
 
-      if (error) throw new Error("Failed to load orders.");
-      return { bookings: orders, recent: [], packageLocales: [], staticCounts: {} };
-    },
+---
 
-    // Opsional: subscribe ke perubahan realtime (untuk live update)
-    subscribeLiveUpdate(onEvent) {
-      const channel = supabase
-        .channel("my-dashboard-live")
-        .on("postgres_changes", { event: "*", schema: "public", table: "orders" }, onEvent)
-        .subscribe();
-      return () => { supabase.removeChannel(channel); };
-    },
-  };
-}
-```
+## 9. Label & Internasionalisasi
 
-### Custom Data Adapter
+### Tanpa i18n (objek manual)
 
-Adapter menerima parameter objek, bukan positional argument:
+Buat objek labels dengan semua key yang diperlukan:
 
 ```javascript
-export function adaptMyBusinessData({ raw, filters, range, dateLocale, languageCode, labels }) {
-  if (!raw) return createMyEmptyData();
-
-  const orders = raw.bookings || [];
-  let totalConfirmed = 0;
-  let totalRevenue = 0;
-
-  orders.forEach((row) => {
-    if (row.status === "confirmed") {
-      totalConfirmed += 1;
-      totalRevenue += Number(row.total_amount) || 0;
-    }
-  });
-
-  return {
-    stats: {
-      bookingsConfirm: totalConfirmed,
-      revenueConfirm: totalRevenue,
-      avgRevenue: totalConfirmed > 0 ? Math.round(totalRevenue / totalConfirmed) : 0,
-      conversionRate: 0,
-      packages: 0,
-      sections: 0,
-    },
-    charts: {
-      dailyTrends: [],
-      statusDistribution: [],
-      audienceDistribution: [],
-      topPackages: [],
-    },
-    table: { recentBookings: [] },
-  };
-}
+const labels = {
+  // Header
+  title: "Dashboard",
+  refresh: "Refresh",
+  liveUpdate: "Live",
+  loadFailed: "Gagal memuat data.",
+  retry: "Coba Lagi",
 
-export function createMyEmptyData() {
-  return {
-    stats: { bookingsConfirm: 0, revenueConfirm: 0, avgRevenue: 0,
-             conversionRate: 0, packages: 0, sections: 0 },
-    charts: { dailyTrends: [], statusDistribution: [],
-              audienceDistribution: [], topPackages: [] },
-    table: { recentBookings: [] },
-  };
-}
-```
+  // Filter
+  confirmedOnly: "Confirmed",
+  pendingOnly: "Pending",
+  allStatus: "Semua Status",
+  showPendingOverlay: "Tampilkan pending",
+  allAudience: "Semua",
+  audienceDomestic: "Domestic",
+  audienceForeign: "Foreign",
+  customDate: "Kustom",
+  reset: "Reset",
+  topSort: "Urutkan",
+  sortBookings: "Qty Terjual",
+  sortRevenue: "Revenue",
+  sortDesc: "Turun",
+  sortAsc: "Naik",
 
----
+  // Stat cards (sesuaikan dengan valueKey di config)
+  confirmedBookings: "Total Pesanan",
+  confirmedRevenue: "Total Pendapatan",
+  avgRevenue: "Rata-rata / Pesanan",
+  conversionRate: "Conversion Rate",
+  totalProducts: "Total Produk",
 
-## 🌐 Label & i18n
+  // Chart & tabel
+  dailyTrends: "Tren Harian",
+  statusDistribution: "Distribusi Status",
+  audienceDistribution: "Distribusi Audiens",
+  topPackages: "Produk Terlaris",
+  recentBookings: "Pesanan Terbaru",
+  date: "Tanggal",
+  customer: "Pelanggan",
+  package: "Produk",
+  audience: "Audiens",
+  total: "Total",
+  status: "Status",
+  noRecentBookings: "Belum ada pesanan",
 
-### Tanpa i18n (plain object)
+  // Chart metrics
+  bookingsMetric: "Pesanan",
+  revenueMetric: "Pendapatan",
+  pendingMetric: "Pesanan (Pending)",
+  confirmedBookingMetric: "Pesanan (Confirmed)",
+  confirmedRevenueMetric: "Pendapatan (Confirmed)",
+  unknownAudience: "Unknown",
 
-Buat objek label secara manual (lihat contoh di Quick Start).
+  // Fungsi formatter (wajib ada)
+  dayLabel: (n) => `${n} hari`,
+  formatStatusLabel: (status) => ({
+    confirmed: "Confirmed",
+    pending: "Pending",
+    cancelled: "Cancelled",
+    shipped: "Dikirim",
+    delivered: "Terkirim",
+  })[status] || status,
+  formatAudienceLabel: (value) => value || "Unknown",
+};
+```
 
 ### Dengan react-i18next
 
-```javascript
+```jsx
 import { useTranslation } from "react-i18next";
 import { createDashboardLabels } from "@rozaqi02/reusable-dashboard";
 
@@ -391,180 +743,136 @@ function Dashboard() {
   const { t, i18n } = useTranslation();
   const languageCode = (i18n.language || "id").slice(0, 2);
   const dateLocale = languageCode === "id" ? "id-ID" : "en-US";
-
-  // createDashboardLabels menerima fungsi t dari react-i18next
   const labels = useMemo(() => createDashboardLabels(t), [t]);
   // ...
 }
 ```
 
+> `createDashboardLabels(t)` menggunakan key i18n dari namespace default.
+> Pastikan file terjemahan kamu memiliki key `admin.dashboard.*`.
+
 ---
 
-## 📖 API Reference
+## 10. API Reference Lengkap
 
-### Configs
+### Config
 
-| Export | Deskripsi |
-|--------|-----------|
-| `cidikaWidgetConfig` | Config dashboard travel agency |
-| `tokoSepatuWidgetConfig` | Config dashboard toko online |
-| `dummyUmkmWidgetConfig` | Config dashboard bisnis generik |
+| Export | Tipe | Deskripsi |
+|--------|------|-----------|
+| `cidikaWidgetConfig` | Object | Config dashboard Cidika Travel |
+| `tokoSepatuWidgetConfig` | Object | Config dashboard Toko Sepatu |
+| `dummyUmkmWidgetConfig` | Object | Config dashboard UMKM generik |
 
-### Data Sources
+### Data Source
 
 | Export | Parameter | Deskripsi |
 |--------|-----------|-----------|
 | `createCidikaSupabaseSource(supabase)` | Supabase client | Data source Cidika Travel |
 | `createTokoSepatuSupabaseSource(supabase)` | Supabase client | Data source Toko Sepatu |
 
-### Data Adapters
-
-| Export | Deskripsi |
-|--------|-----------|
-| `adaptCidikaDashboardData({ raw, filters, range, dateLocale, languageCode, labels })` | Adapter Cidika Travel |
-| `createEmptyDashboardData()` | Empty state Cidika Travel |
-| `adaptTokoSepatuData({ raw, filters, range, dateLocale, languageCode, labels })` | Adapter Toko Sepatu |
-| `createEmptyTokoSepatuData()` | Empty state Toko Sepatu |
-| `adaptDummyUmkmData({ raw, filters, range, dateLocale, languageCode, labels })` | Adapter Dummy UMKM |
-| `createEmptyDummyUmkmData()` | Empty state Dummy UMKM |
+### Data Adapter
 
-### Hooks
-
-| Hook | Deskripsi |
-|------|-----------|
-| `useReusableDashboard(options)` | Hook utama orkestrasi dashboard |
-| `useRealtimeUpdate(options)` | Hook subscription Supabase Realtime |
+| Export | Parameter | Deskripsi |
+|--------|-----------|-----------|
+| `adaptCidikaDashboardData({ raw, filters, range, dateLocale, languageCode, labels })` | — | Adapter Cidika |
+| `createEmptyDashboardData()` | — | Empty state Cidika |
+| `adaptTokoSepatuData({ raw, filters, range, dateLocale, labels })` | — | Adapter Toko Sepatu |
+| `createEmptyTokoSepatuData()` | — | Empty state Toko Sepatu |
+| `adaptDummyUmkmData({ raw, filters, range, dateLocale, labels })` | — | Adapter UMKM generik |
+| `createEmptyDummyUmkmData()` | — | Empty state UMKM generik |
 
-**useReusableDashboard options:**
+### Hook Utama
 
 ```typescript
-{
+const state = useReusableDashboard({
   config: object,              // Widget configuration
-  dataSource: object,          // Objek dengan fetchDashboardSnapshot + subscribeLiveUpdate
-  adapter: Function,           // ({ raw, filters, range, dateLocale, languageCode, labels }) => data
-  createEmptyState: Function,  // () => data kosong
-  languageCode: string,        // "id" | "en"
-  dateLocale: string,          // "id-ID" | "en-US"
-  labels: object,              // Objek label teks UI
-}
+  dataSource: object,          // Objek dari createXxxSupabaseSource()
+  adapter: Function,           // Fungsi adaptXxxData
+  createEmptyState: Function,  // Fungsi createEmptyXxxData
+  languageCode: "id" | "en",
+  dateLocale: "id-ID" | "en-US",
+  labels: object,
+});
+
+// state yang dikembalikan:
+state.data              // Data dashboard terproses
+state.loading           // boolean — sedang loading?
+state.error             // string — pesan error (kosong jika tidak ada)
+state.filters           // State filter aktif saat ini
+state.updateFilter      // (field: string, value: any) => void
+state.resetFilters      // () => void
+state.refresh           // ({ silent?: boolean }) => void
+state.liveUpdateEnabled // boolean — realtime subscription aktif?
+state.lastUpdatedAt     // Date | null
+state.range             // { fromISO, toISO, daysWindow }
 ```
 
-**Return value useReusableDashboard:**
+### Komponen
 
-```typescript
-{
-  data: object,                // Data dashboard terproses
-  loading: boolean,            // Status loading
-  error: string,               // Pesan error (kosong jika tidak ada)
-  filters: object,             // State filter aktif
-  updateFilter: (field, value) => void,  // Update satu filter
-  resetFilters: () => void,    // Reset semua filter ke default
-  refresh: ({ silent?: boolean }) => void, // Muat ulang data
-  range: { fromISO, toISO, daysWindow }, // Rentang tanggal aktif
-  liveUpdateEnabled: boolean,  // Apakah realtime subscription aktif
-  lastUpdatedAt: Date | null,  // Waktu terakhir data diperbarui
-}
-```
-
-### Components
-
-#### Atoms
-| Komponen | Props Utama | Deskripsi |
-|----------|-------------|-----------|
-| `Button` | `variant` (primary\|secondary\|ghost), `size` (sm\|md\|lg), `onClick`, `disabled` | Tombol aksi |
-| `Input` | `type`, `value`, `onChange`, `placeholder`, `label`, `disabled` | Field teks |
-| `Icon` | `name` (nama Lucide), `size`, `className` | Ikon SVG via registry |
-| `Typography` | `variant` (h1\|h2\|h3\|subheading\|body\|caption\|metric) | Teks hierarki |
-| `Badge` | `status` (confirmed\|pending\|cancelled\|success\|info\|default) | Label status |
-| `SkeletonLoader` | `className` | Placeholder loading |
-
-#### Molecules
-| Komponen | Props Utama | Deskripsi |
-|----------|-------------|-----------|
-| `StatCard` | `label`, `value`, `icon`, `format` (number\|currency\|percent), `trend` (up\|down) | Kartu metrik |
-| `SearchBar` | `value`, `onSearch`, `placeholder` | Input pencarian |
-| `DateRangeFilter` | `value`, `onChange` | Filter tanggal |
-| `ChartHeader` | `title`, `icon`, `actions` | Header grafik |
-
-#### Organisms
-| Komponen | Props Utama | Deskripsi |
-|----------|-------------|-----------|
-| `DataTable` | `columns`, `data`, `labels`, `dateLocale`, `searchable`, `sortable`, `pageSize`, `emptyLabel` | Tabel interaktif |
-| `ChartCard` | `widget`, `labels`, `loading`, `filters`, `chartData` | Kartu grafik |
-| `FilterPanel` | `filters`, `labels`, `onFilterChange`, `onResetFilters` | Panel filter |
-| `SidebarNavigation` | `items`, `activeId`, `onSelect` | Sidebar nav |
-| `TopbarHeader` | `title`, `onRefresh`, `liveUpdateEnabled` | Header atas |
-
-#### Templates & Pages
 | Komponen | Deskripsi |
 |----------|-----------|
-| `DashboardLayout` | Layout dengan slot sidebar dan main content |
-| `ReusableDashboardView` | Halaman dashboard lengkap (gunakan ini untuk integrasi cepat) |
-
-### Utility Functions
-
-| Function | Signature | Deskripsi |
-|----------|-----------|-----------|
-| `createDashboardLabels(t)` | `t: Function` | Buat objek label dari fungsi i18n |
-| `createDefaultFilters(base?)` | `base?: object` | Buat filter default |
-| `resolveDateRange({ daysPreset, dateFrom, dateTo })` | — | Resolve range ke `{ fromISO, toISO, daysWindow }` |
-| `formatYYYYMMDD(date)` | `date: Date` | Format tanggal ke `YYYY-MM-DD` |
-| `formatIDR(value)` | `value: number` | Format angka ke Rupiah (`1.500.000`) |
-| `formatDate(value, locale)` | `value: string, locale: string` | Format tanggal dengan locale |
-| `shortId(value, length?)` | `value: string, length?: number` | Potong string (default 8 karakter) |
-| `toNumber(value)` | `value: any` | Konversi ke angka finite, fallback 0 |
-| `buildDayBuckets(daysWindow, fromISO, dateLocale)` | — | Bangun array bucket harian untuk chart |
-| `sortMapEntries(map, direction)` | `direction: "asc"\|"desc"` | Urutkan entri Map berdasarkan nilai |
-| `resolveIcon(name)` | `name: string` | Resolve nama string ke komponen Lucide |
+| `ReusableDashboardView` | Halaman dashboard lengkap — gunakan ini untuk integrasi cepat |
+| `StatCard` | Kartu metrik dengan warna aksen |
+| `ChartCard` | Kartu grafik (area/pie/bar) |
+| `DataTable` | Tabel dengan search, sort, pagination |
+| `FilterPanel` | Panel filter |
+| `SearchBar` | Input pencarian |
+| `DateRangeFilter` | Filter rentang tanggal (dropdown picker) |
+| `Badge` | Label status berwarna |
+| `Button` | Tombol |
+| `Input` | Input field |
+| `Typography` | Komponen teks |
+| `Icon` | Ikon (Lucide) |
+| `SkeletonLoader` | Placeholder loading |
+| `DashboardLayout` | Template layout dengan slot sidebar dan content |
+| `SidebarNavigation` | Navigasi sidebar |
+| `TopbarHeader` | Header atas |
+
+### Utility
+
+| Function | Deskripsi |
+|----------|-----------|
+| `createDashboardLabels(t)` | Buat labels dari fungsi `t` react-i18next |
+| `createDefaultFilters(base?)` | Buat state filter default |
+| `resolveDateRange({ daysPreset, dateFrom, dateTo })` | Resolve ke `{ fromISO, toISO, daysWindow }` |
+| `formatYYYYMMDD(date)` | Format `Date` ke `"YYYY-MM-DD"` |
+| `formatIDR(value)` | Format angka ke format Rupiah (`1.500.000`) |
+| `formatDate(value, locale)` | Format ISO date string dengan locale |
+| `shortId(value, length?)` | Potong string (default 8 karakter) |
+| `toNumber(value)` | Konversi ke angka, fallback ke 0 |
+| `buildDayBuckets(daysWindow, fromISO, dateLocale)` | Bangun array bucket harian untuk chart |
+| `sortMapEntries(map, direction)` | Urutkan entri Map berdasarkan nilai |
 
 ---
 
-## 🛠️ Development
+## 11. Pengembangan & Kontribusi
 
 ```bash
-# Clone & install
-git clone <repo-url>
+# Clone repository
+git clone https://github.com/rozaqi02/reusable-dashboard-umkm.git
 cd reusable-dashboard-umkm
+
+# Install dependencies
 npm install
 
-# Build production
-npm run build
+# Build
+npm run build        # Output ke dist/
 
-# Run tests
-npm test
+# Test
+npm test             # Jest + React Testing Library
+npm test -- --coverage  # Lihat code coverage
 
-# Test via npm link
-npm link
-cd /path/to/your-project
-npm link @rozaqi02/reusable-dashboard
+# 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
 ```
 
-**Output build** (`dist/`):
-- `dist/index.js` — ESM (untuk Vite, modern bundler)
-- `dist/index.cjs` — CommonJS (untuk CRA, Node.js)
-- `dist/index.js.map` + `dist/index.cjs.map` — Source maps
-
----
-
-## 📄 Examples
-
-| Folder | Domain | Konten |
-|--------|--------|--------|
-| `examples/cidika-travel-example/` | Travel agency | `AdminDashboard.jsx`, schema SQL |
-| `examples/toko-sepatu-example/` | Toko online | `TokoSepatuDashboard.jsx`, schema SQL, seed data |
-| `examples/dummy-umkm-example/` | UMKM generik | `DummyUmkmDashboard.jsx` |
-
----
-
-## 🔒 License
-
-Proprietary — hanya untuk penggunaan oleh pihak yang berwenang.
-
 ---
 
-## 📞 Support
+## License
 
-- Email: abrorrozaqi@gmail.com
+MIT — Ahmad Abror Rozaqi Fatoni
 
 ---