@gemafajarramadhan/dynamic-ui 1.1.28 → 1.1.29

package/README.md

@@ -19,6 +19,13 @@ Library **Vue 3** component yang bisa digunakan di berbagai framework (Vue, Reac
   - [Penggunaan di Vue 3 (Import Per Komponen)](#penggunaan-di-vue-3-import-per-komponen)
   - [Penggunaan di Vue 3 (Global Plugin)](#penggunaan-di-vue-3-global-plugin)
   - [Penggunaan di Nuxt 3](#penggunaan-di-nuxt-3-vue-components)
+- [DCodeDataTable – Tabel Dinamis](#dcodedatatable--tabel-dinamis)
+  - [Props Utama](#props-utama)
+  - [Pola 1 — fetchHandler (MFE)](#pola-1--fetchhandler--disarankan-untuk-mfe)
+  - [Pola 2 — Static Data](#pola-2--static-data-consumer-fetch-di-luar)
+  - [Pola 3 — Realtime Socket](#pola-3--realtime-socket-consumer-kelola-socket)
+  - [Format Response](#format-response-yang-didukung)
+  - [Expose Methods](#expose-methods-via-ref)
 - [DCodeAutoComplete – Komponen dengan API](#dcodeautocomplete--komponen-dengan-api)
 - [Web Components (Framework Agnostic)](#web-components-framework-agnostic)
   - [API Referensi Web Components](#api-referensi-web-components)
@@ -379,6 +386,269 @@ Kemudian gunakan di page atau component manapun:
 
 ---
 
+## DCodeDataTable – Tabel Dinamis
+
+`DCodeDataTable` adalah komponen tabel dinamis yang mendukung **pagination server-side**, **sorting**, **filtering**, **action buttons**, dan **badge kondisional** — seluruhnya dikonfigurasi via JSON schema.
+
+Komponen ini dirancang sebagai **micro-frontend**: consumer bertanggung jawab penuh atas HTTP client, auth token, dan sistem permission.
+
+---
+
+### Props Utama
+
+| Prop | Tipe | Default | Deskripsi |
+|------|------|---------|-----------|
+| `table-config` | `Object` | — | Config JSON (kolom, filter, action, pagination) |
+| `fetch-handler` | `(params) => Promise<any>` | — | **[MFE]** Consumer kontrol penuh fetch. Component tidak hit endpoint sama sekali. |
+| `http-client` | `({ url, method, data }) => Promise<any>` | — | **[MFE]** Axios instance consumer untuk action tombol row/header (DELETE, PATCH, dll.) |
+| `action-access-checker` | `(path, action) => boolean` | `() => true` | **[MFE]** Fungsi RBAC dari consumer. Default: semua action allow. |
+| `ignore-permissions` | `boolean` | `false` | Matikan filter permission sepenuhnya |
+| `data` | `any[]` | `[]` | Data statis (tanpa API); pakai jika consumer sudah fetch di luar |
+| `loading` | `boolean` | `false` | Loading state untuk mode data statis |
+| `columns` | `TableColumn[]` | `[]` | Kolom manual (tanpa table-config) |
+| `per-page` | `number` | `10` | Jumlah baris per halaman awal |
+| `show-pagination` | `boolean` | `true` | Tampilkan pagination |
+| `has-actions` | `boolean` | `false` | Tampilkan kolom aksi (untuk mode kolom manual) |
+| `api-url` | `string` | — | URL endpoint langsung (tanpa table-config) |
+| `api-method` | `string` | `'POST'` | HTTP method untuk apiUrl |
+| `api-params` | `object` | `{}` | Parameter tetap yang selalu disertakan di setiap request |
+
+### Events
+
+| Event | Payload | Deskripsi |
+|-------|---------|-----------|
+| `@action` | `{ action, row, selection? }` | Dipanggil saat tombol action diklik |
+| `@update:selection` | `any[]` | Dipanggil saat checkbox selection berubah |
+| `@update:page` | `number` | Dipanggil saat halaman berganti |
+
+---
+
+### Pola 1 — `fetchHandler` ⭐ Disarankan untuk MFE
+
+Consumer kontrol penuh HTTP. Component tidak hit endpoint sama sekali — cocok untuk menghindari error 401.
+
+```vue
+<template>
+  <DCodeDataTable
+    :table-config="tableConfig"
+    :fetch-handler="fetchUsers"
+    :http-client="httpClient"
+    :action-access-checker="checkPermission"
+    @action="handleAction"
+  />
+</template>
+
+<script setup lang="ts">
+import { DCodeDataTable } from '@gemafajarramadhan/dynamic-ui'
+import axios from '@/lib/axios' // axios instance consumer — interceptor token sudah terpasang
+
+// 1. fetchHandler: dipanggil tiap page/filter/sort/search change
+//    params: { page, perPage, keyword?, ...filters }
+const fetchUsers = async (params: Record<string, any>) => {
+  const { data } = await axios.post('/api/users/list', params)
+  return data
+}
+
+// 2. httpClient: untuk call dari tombol action row (delete, toggle, dll.)
+const httpClient = async ({ url, method, data }: any) => {
+  const res = await axios({ url, method, data })
+  return res.data
+}
+
+// 3. Permission checker dari sistem RBAC consumer
+const checkPermission = (path: string, action: string): boolean => {
+  return useAuthStore().can(`${path}:${action}`)
+}
+
+// 4. Handle action event dari tabel
+const handleAction = ({ action, row, selection }: any) => {
+  if (action === 'edit')   router.push(`/users/${row.id}/edit`)
+  if (action === 'delete') deleteUser(row.id)
+  if (action === 'export') exportSelected(selection)
+}
+
+// 5. Konfigurasi tabel via JSON schema
+const tableConfig = {
+  headers: [
+    { key: 'no',    labelID: 'No',    labelEN: 'No',    align: 'CENTER' },
+    { key: 'name',  labelID: 'Nama',  labelEN: 'Name',  align: 'LEFT' },
+    { key: 'email', labelID: 'Email', labelEN: 'Email', align: 'LEFT' },
+    {
+      key: 'status',
+      labelID: 'Status', labelEN: 'Status',
+      custom: {
+        type: 'BADGE',
+        conditionBadge: [
+          { value: 'active',   labelID: 'Aktif',    labelEN: 'Active',   color: 'success' },
+          { value: 'inactive', labelID: 'Nonaktif', labelEN: 'Inactive', color: 'danger' },
+        ],
+      },
+    },
+    {
+      key: 'action',
+      labelID: 'Aksi', labelEN: 'Actions',
+      custom: {
+        type: 'ACTION',
+        actionCustom: [
+          {
+            permission: 'EDIT',
+            propsActionCustom: {
+              labelID: 'Edit', labelEN: 'Edit',
+              icon: 'SquarePen', actionType: 'edit', bgColor: 'primary',
+            },
+          },
+          {
+            permission: 'DELETE',
+            requireConfirm: true,
+            propCustomMessage: {
+              titleID: 'Hapus Data', titleEN: 'Delete',
+              messageID: 'Yakin ingin menghapus?', messageEN: 'Are you sure?',
+            },
+            propsActionCustom: {
+              labelID: 'Hapus', labelEN: 'Delete',
+              icon: 'Trash2', actionType: 'delete', bgColor: 'red',
+            },
+          },
+        ],
+      },
+    },
+  ],
+  filters: [
+    {
+      seq: 1, model: 'name', labelID: 'Nama', labelEN: 'Name', type: 'TEXT',
+    },
+    {
+      seq: 2, model: 'status', labelID: 'Status', labelEN: 'Status', type: 'SELECT',
+      propsFilters: {
+        items: [
+          { value: 'active',   label: 'Active' },
+          { value: 'inactive', label: 'Inactive' },
+        ],
+      },
+    },
+  ],
+  actionGlobal: [
+    {
+      permission: 'CREATE',
+      propsActionGlobal: {
+        labelID: 'Tambah', labelEN: 'Add New',
+        icon: 'Plus', variant: 'default',
+        route: '/users/create',
+      },
+    },
+  ],
+  pagination: true,
+}
+</script>
+```
+
+---
+
+### Pola 2 — Static Data (consumer fetch di luar)
+
+Pakai ketika consumer sudah fetch data sendiri dan ingin sekadar menampilkan tabel.
+
+```vue
+<template>
+  <DCodeDataTable
+    :columns="columns"
+    :data="users"
+    :loading="isLoading"
+    has-actions
+    ignore-permissions
+    @action="handleAction"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import axios from '@/lib/axios'
+
+const users = ref([])
+const isLoading = ref(false)
+
+onMounted(async () => {
+  isLoading.value = true
+  const { data } = await axios.get('/api/users')
+  users.value = data.data
+  isLoading.value = false
+})
+
+const columns = [
+  { key: 'no',    label: 'No',    align: 'center' },
+  { key: 'name',  label: 'Nama',  align: 'left' },
+  { key: 'email', label: 'Email', align: 'left' },
+]
+</script>
+```
+
+---
+
+### Pola 3 — Realtime Socket (consumer kelola socket)
+
+Consumer connect ke WebSocket sendiri, push data ke tabel melalui `:data`.
+
+```vue
+<template>
+  <DCodeDataTable :columns="columns" :data="realtimeData" ignore-permissions />
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted } from 'vue'
+import { io } from 'socket.io-client'
+
+const realtimeData = ref([])
+let socket: any = null
+
+onMounted(() => {
+  socket = io('wss://your-server.com', {
+    auth: { token: localStorage.getItem('token') }
+  })
+  socket.emit('dashboard:list', { page: 1, perPage: 10 })
+  socket.on('dashboard:result', (res: any) => {
+    realtimeData.value = res.data ?? res
+  })
+})
+
+onUnmounted(() => socket?.disconnect())
+</script>
+```
+
+---
+
+### Format Response yang Didukung
+
+Component secara otomatis mendeteksi berbagai format response API:
+
+```json
+{ "data": [], "totalData": 100 }    ✅ (disarankan)
+{ "data": [], "maxPage": 10 }       ✅
+{ "items": [], "total": 100 }       ✅
+{ "list": [], "total": 100 }        ✅
+{ "rows": [], "count": 100 }        ✅
+{ "result": [], "total": 100 }      ✅
+[]                                  ✅ (array langsung)
+```
+
+---
+
+### Expose Methods (via `ref`)
+
+```typescript
+const tableRef = ref()
+
+tableRef.value.fetchData()      // Refresh data (panggil ulang fetchHandler)
+tableRef.value.handleRefresh()  // Reset filter & refresh
+tableRef.value.resetFilters()   // Reset nilai filter saja (tanpa fetch)
+console.log(tableRef.value.filters) // Reactive nilai filter saat ini
+```
+
+```vue
+<DCodeDataTable ref="tableRef" :fetch-handler="fetchUsers" ... />
+```
+
+---
+
 ## DCodeAutoComplete – Komponen dengan API
 
 `DCodeAutoComplete` adalah komponen autocomplete yang bisa **langsung fetch data dari API** menggunakan konfigurasi yang sudah di-set di host project.