@rozaqi02/reusable-dashboard 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [1.0.0] - 2026-04-15
+
+### Added
+
+1. Initial reusable dashboard module release.
+2. Reusable dashboard presentation components (`stat`, `chart`, `table`, `layout`).
+3. Widget configuration layer for travel and dummy UMKM domain.
+4. Data adapter and Supabase data source with live update subscription.
+5. Hook orchestration for filters, snapshot refresh, and realtime update.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmad Abror Rozaqi Fatoni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,571 @@
+# @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.
+
+[![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)](#)
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @rozaqi02/reusable-dashboard
+```
+
+## ✅ Prerequisites
+
+- **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
+
+Install peer dependencies yang dibutuhkan:
+
+```bash
+npm install react react-dom recharts @supabase/supabase-js lucide-react prop-types tailwindcss
+```
+
+> **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)).
+
+---
+
+## 🚀 Quick Start
+
+### Step 1: Setup Supabase Client
+
+Buat file `src/lib/supabaseClient.js`:
+
+```javascript
+import { createClient } from '@supabase/supabase-js';
+
+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
+);
+```
+
+Buat file `.env` di root project:
+
+```env
+# Vite
+VITE_SUPABASE_URL=https://your-project.supabase.co
+VITE_SUPABASE_ANON_KEY=your-anon-key
+
+# Create React App
+# REACT_APP_SUPABASE_URL=https://your-project.supabase.co
+# REACT_APP_SUPABASE_ANON_KEY=your-anon-key
+```
+
+### Step 2: Setup Database Schema
+
+Jalankan SQL schema di Supabase SQL Editor sesuai domain bisnis:
+
+| Domain | File SQL |
+|--------|----------|
+| Cidika Travel | `examples/cidika-travel-example/supabase-schema.sql` |
+| Toko Sepatu | `examples/toko-sepatu-example/supabase-schema.sql` |
+
+### Step 3: Implementasi Dashboard
+
+Contoh menggunakan preset **Toko Sepatu**:
+
+```jsx
+import React, { useMemo } from "react";
+import { supabase } from "./lib/supabaseClient";
+import {
+  ReusableDashboardView,
+  tokoSepatuWidgetConfig,
+  createTokoSepatuSupabaseSource,
+  adaptTokoSepatuData,
+  createEmptyTokoSepatuData,
+  useReusableDashboard,
+} from "@rozaqi02/reusable-dashboard";
+
+// Inisialisasi data source satu kali di luar komponen
+const source = createTokoSepatuSupabaseSource(supabase);
+
+// Label minimal tanpa i18n — override semua key yang diperlukan
+const labels = {
+  title: "Dashboard Toko Sepatu",
+  refresh: "Refresh",
+  liveUpdate: "Live",
+  loadFailed: "Gagal memuat data.",
+  retry: "Coba Lagi",
+  confirmedOnly: "Confirmed",
+  pendingOnly: "Pending",
+  allStatus: "Semua Status",
+  showPendingOverlay: "Tampilkan pending",
+  allAudience: "Semua",
+  customDate: "Kustom",
+  reset: "Reset",
+  topSort: "Urutkan",
+  sortBookings: "Qty",
+  sortRevenue: "Revenue",
+  sortDesc: "Turun",
+  sortAsc: "Naik",
+  confirmedBookings: "Total Pesanan",
+  confirmedRevenue: "Total Pendapatan",
+  avgRevenue: "Rata-rata / Pesanan",
+  conversionRate: "Conversion Rate",
+  totalProducts: "Total Produk",
+  dailyTrends: "Tren Harian",
+  statusDistribution: "Distribusi Status",
+  topPackages: "Produk Terlaris",
+  recentBookings: "Pesanan Terbaru",
+  date: "Tanggal",
+  customer: "Pelanggan",
+  package: "Produk",
+  total: "Total",
+  status: "Status",
+  noRecentBookings: "Belum ada pesanan",
+  bookingsMetric: "Pesanan",
+  revenueMetric: "Pendapatan",
+  pendingMetric: "Pesanan (Pending)",
+  confirmedBookingMetric: "Pesanan (Confirmed)",
+  confirmedRevenueMetric: "Pendapatan (Confirmed)",
+  unknownAudience: "Unknown",
+  dayLabel: (count) => `${count} hari`,
+  formatStatusLabel: (s) => ({ confirmed: "Confirmed", pending: "Pending", cancelled: "Cancelled" })[s] || s,
+  formatAudienceLabel: (v) => v || "Unknown",
+};
+
+export default function Dashboard() {
+  const state = useReusableDashboard({
+    config: tokoSepatuWidgetConfig,
+    dataSource: source,
+    adapter: adaptTokoSepatuData,
+    createEmptyState: createEmptyTokoSepatuData,
+    languageCode: "id",
+    dateLocale: "id-ID",
+    labels,
+  });
+
+  return (
+    <ReusableDashboardView
+      config={tokoSepatuWidgetConfig}
+      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}
+    />
+  );
+}
+```
+
+> **Menggunakan react-i18next?** Gunakan `createDashboardLabels(t)` dari export modul
+> sebagai pengganti objek labels di atas. Lihat [bagian i18n](#-label--i18n).
+
+### Step 4: Jalankan Aplikasi
+
+```bash
+npm run dev   # Vite
+# atau
+npm start     # Create React App
+```
+
+---
+
+## 📚 Available Presets
+
+### 1. Cidika Travel (Travel Agency)
+
+```javascript
+import {
+  cidikaWidgetConfig,
+  createCidikaSupabaseSource,
+  adaptCidikaDashboardData,
+  createEmptyDashboardData,
+} from "@rozaqi02/reusable-dashboard";
+
+const source = createCidikaSupabaseSource(supabase);
+```
+
+Tabel Supabase yang dibutuhkan: `bookings`, `packages`, `package_locales`, `page_sections`
+
+### 2. Toko Sepatu (Online Shop)
+
+```javascript
+import {
+  tokoSepatuWidgetConfig,
+  createTokoSepatuSupabaseSource,
+  adaptTokoSepatuData,
+  createEmptyTokoSepatuData,
+} from "@rozaqi02/reusable-dashboard";
+
+const source = createTokoSepatuSupabaseSource(supabase);
+```
+
+Tabel Supabase yang dibutuhkan: `orders`, `order_items`, `products`, `customers`
+
+### 3. Dummy UMKM (Generic)
+
+```javascript
+import {
+  dummyUmkmWidgetConfig,
+  adaptDummyUmkmData,
+  createEmptyDummyUmkmData,
+} from "@rozaqi02/reusable-dashboard";
+```
+
+> Dummy UMKM tidak memiliki data source khusus.
+> Gunakan data source Toko Sepatu atau buat sendiri.
+
+---
+
+## 🎨 Customization
+
+### Custom Widget Configuration
+
+Struktur konfigurasi yang benar (sesuai kontrak API modul):
+
+```javascript
+export const myConfig = {
+  id: "my-business.dashboard",
+  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: "",
+  },
+  widgets: {
+    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"
+      },
+      {
+        id: "totalRevenue",
+        label: "confirmedRevenue",
+        icon: "DollarSign",
+        valueKey: "revenueConfirm",
+        format: "currency",
+      },
+    ],
+    charts: [
+      {
+        id: "dailyTrends",
+        type: "dailyArea",       // "dailyArea" | "statusPie" | "audiencePie" | "topPackagesBar"
+        label: "dailyTrends",
+        icon: "BarChart3",
+      },
+      {
+        id: "statusDist",
+        type: "statusPie",
+        label: "statusDistribution",
+        icon: "PieChart",
+      },
+    ],
+    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: "total",    label: "total",    accessor: "totalIDR",     type: "currency" },
+        {
+          id: "status", label: "status", accessor: "statusLabel",
+          type: "statusBadge", statusAccessor: "status",
+        },
+      ],
+    },
+  },
+};
+```
+
+### Custom Data Source
+
+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);
+
+      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); };
+    },
+  };
+}
+```
+
+### Custom Data Adapter
+
+Adapter menerima parameter objek, bukan positional argument:
+
+```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: [] },
+  };
+}
+
+export function createMyEmptyData() {
+  return {
+    stats: { bookingsConfirm: 0, revenueConfirm: 0, avgRevenue: 0,
+             conversionRate: 0, packages: 0, sections: 0 },
+    charts: { dailyTrends: [], statusDistribution: [],
+              audienceDistribution: [], topPackages: [] },
+    table: { recentBookings: [] },
+  };
+}
+```
+
+---
+
+## 🌐 Label & i18n
+
+### Tanpa i18n (plain object)
+
+Buat objek label secara manual (lihat contoh di Quick Start).
+
+### Dengan react-i18next
+
+```javascript
+import { useTranslation } from "react-i18next";
+import { createDashboardLabels } from "@rozaqi02/reusable-dashboard";
+
+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]);
+  // ...
+}
+```
+
+---
+
+## 📖 API Reference
+
+### Configs
+
+| Export | Deskripsi |
+|--------|-----------|
+| `cidikaWidgetConfig` | Config dashboard travel agency |
+| `tokoSepatuWidgetConfig` | Config dashboard toko online |
+| `dummyUmkmWidgetConfig` | Config dashboard bisnis generik |
+
+### Data Sources
+
+| 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 |
+
+### Hooks
+
+| Hook | Deskripsi |
+|------|-----------|
+| `useReusableDashboard(options)` | Hook utama orkestrasi dashboard |
+| `useRealtimeUpdate(options)` | Hook subscription Supabase Realtime |
+
+**useReusableDashboard options:**
+
+```typescript
+{
+  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
+}
+```
+
+**Return value useReusableDashboard:**
+
+```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 |
+
+---
+
+## 🛠️ Development
+
+```bash
+# Clone & install
+git clone <repo-url>
+cd reusable-dashboard-umkm
+npm install
+
+# Build production
+npm run build
+
+# Run tests
+npm test
+
+# Test via npm link
+npm link
+cd /path/to/your-project
+npm link @rozaqi02/reusable-dashboard
+```
+
+**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
+
+- Email: abrorrozaqi@gmail.com
+
+---
+
+**Made with ❤️ for UMKM Indonesia**