@gemafajarramadhan/dynamic-ui 1.0.5 → 1.0.7

package/README.md

@@ -8,11 +8,18 @@ Library **Vue 3** component yang bisa digunakan di berbagai framework (Vue, Reac
 
 - [Fitur](#fitur)
 - [Instalasi](#instalasi)
+- [⚡ Konfigurasi API (WAJIB)](#-konfigurasi-api-wajib)
+  - [Vue 3](#konfigurasi-api-di-vue-3)
+  - [Nuxt 3](#konfigurasi-api-di-nuxt-3)
+  - [React / Next.js](#konfigurasi-api-di-react--nextjs)
+  - [Angular](#konfigurasi-api-di-angular)
+  - [Vanilla JS (window global)](#konfigurasi-api-via-window-global)
 - [Komponen Base (Vue Components)](#komponen-base-vue-components)
   - [Daftar Komponen](#daftar-komponen)
   - [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)
+- [DCodeAutoComplete – Komponen dengan API](#dcodeautocomplete--komponen-dengan-api)
 - [Web Components (Framework Agnostic)](#web-components-framework-agnostic)
   - [API Referensi Web Components](#api-referensi-web-components)
   - [Logic Registry API](#logic-registry-api)
@@ -36,6 +43,7 @@ Library **Vue 3** component yang bisa digunakan di berbagai framework (Vue, Reac
 - 🔌 **Logic Registry** – Daftarkan custom business logic dari aplikasi host tanpa perlu memodifikasi library.
 - 🎨 **Style Bundled** – CSS sudah ter-bundle, cukup import satu file style.
 - 🌐 **i18n Ready** – Mendukung internasionalisasi (vue-i18n).
+- 🔐 **API Config** – Base URL dan auth token diambil dari **host project**, bukan dari env package ini.
 
 ---
 
@@ -54,6 +62,173 @@ pnpm add @gemafajarramadhan/dynamic-ui
 
 ---
 
+## ⚡ Konfigurasi API (WAJIB)
+
+> **Penting:** Komponen seperti `DCodeAutoComplete` melakukan HTTP request ke API. Base URL dan auth token **diambil dari host project**, bukan dari `.env` package ini. Anda **wajib** mengkonfigurasi ini di aplikasi host sebelum menggunakan komponen.
+
+Library menggunakan sistem konfigurasi terpusat via `setApiConfig()` (atau via Vue Plugin). Berikut urutan prioritas resolusi base URL:
+
+| Prioritas | Sumber |
+|-----------|--------|
+| 1️⃣ Tertinggi | `apiBaseUrl` via plugin / `setApiConfig()` |
+| 2️⃣ | `window.__MICRO_API_BASE_URL__` (global) |
+| 3️⃣ | `import.meta.env.VITE_API_BASE_URL` (env host) |
+| 4️⃣ Terendah | `''` (same-origin fallback) |
+
+---
+
+### Konfigurasi API di Vue 3
+
+Cara paling direkomendasikan: lewatkan config saat `app.use()`.
+
+```js
+// main.js
+import { createApp } from 'vue'
+import App from './App.vue'
+import DynamicUI from '@gemafajarramadhan/dynamic-ui'
+import '@gemafajarramadhan/dynamic-ui/style.css'
+
+const app = createApp(App)
+
+app.use(DynamicUI, {
+  // ✅ Base URL API dari env HOST project
+  apiBaseUrl: import.meta.env.VITE_API_BASE_URL,
+
+  // ✅ Token auth terkini (dipanggil setiap request)
+  getAuthToken: () => localStorage.getItem('access_token'),
+
+  // ✅ Atau gunakan custom headers penuh (override Authorization)
+  // getHeaders: () => ({
+  //   Authorization: `Bearer ${store.getters.token}`,
+  //   'X-App-ID': 'my-app',
+  // }),
+
+  // ✅ Callback ketika response 401 (Unauthorized)
+  onUnauthorized: () => {
+    router.push('/login')
+  },
+})
+
+app.mount('#app')
+```
+
+> File `.env` di host project Anda:
+> ```env
+> VITE_API_BASE_URL=https://api.example.com
+> ```
+
+---
+
+### Konfigurasi API di Nuxt 3
+
+```ts
+// plugins/dynamic-ui.ts
+import DynamicUI from '@gemafajarramadhan/dynamic-ui'
+import '@gemafajarramadhan/dynamic-ui/style.css'
+
+export default defineNuxtPlugin((nuxtApp) => {
+  const config = useRuntimeConfig()
+
+  nuxtApp.vueApp.use(DynamicUI, {
+    // Ambil dari runtimeConfig Nuxt
+    apiBaseUrl: config.public.apiBaseUrl,
+
+    getAuthToken: () => useCookie('access_token').value ?? null,
+
+    onUnauthorized: () => {
+      navigateTo('/login')
+    },
+  })
+})
+```
+
+> File `nuxt.config.ts` di host project:
+> ```ts
+> export default defineNuxtConfig({
+>   runtimeConfig: {
+>     public: {
+>       apiBaseUrl: process.env.VITE_API_BASE_URL, // set di .env
+>     },
+>   },
+> })
+> ```
+
+---
+
+### Konfigurasi API di React / Next.js
+
+Gunakan fungsi `setApiConfig()` secara langsung (tidak perlu Vue plugin).
+
+```ts
+// src/lib/dynamic-ui-config.ts (jalankan sebelum render app)
+import { setApiConfig } from '@gemafajarramadhan/dynamic-ui'
+
+setApiConfig({
+  apiBaseUrl: process.env.NEXT_PUBLIC_API_BASE_URL,
+
+  getAuthToken: () => localStorage.getItem('access_token'),
+
+  onUnauthorized: () => {
+    window.location.href = '/login'
+  },
+})
+```
+
+Panggil di entry point:
+
+```tsx
+// app/layout.tsx atau _app.tsx
+'use client'
+import '@/lib/dynamic-ui-config' // ← jalankan konfigurasi lebih dulu
+import '@gemafajarramadhan/dynamic-ui/style.css'
+```
+
+> File `.env.local` di host project Next.js:
+> ```env
+> NEXT_PUBLIC_API_BASE_URL=https://api.example.com
+> ```
+
+---
+
+### Konfigurasi API di Angular
+
+```ts
+// main.ts
+import { setApiConfig } from '@gemafajarramadhan/dynamic-ui'
+import '@gemafajarramadhan/dynamic-ui'
+import '@gemafajarramadhan/dynamic-ui/style.css'
+
+// Konfigurasi sebelum bootstrap
+setApiConfig({
+  apiBaseUrl: (window as any).__env?.API_BASE_URL || 'https://api.example.com',
+
+  getAuthToken: () => localStorage.getItem('access_token'),
+
+  onUnauthorized: () => {
+    window.location.href = '/login'
+  },
+})
+
+platformBrowserDynamic().bootstrapModule(AppModule)
+```
+
+---
+
+### Konfigurasi API via Window Global
+
+Alternatif tanpa import fungsi – set sebelum library dimuat:
+
+```html
+<script>
+  // Set sebelum import library
+  window.__MICRO_API_BASE_URL__ = 'https://api.example.com'
+  window.__MICRO_AUTH_TOKEN__ = 'your-auth-token' // atau ambil dari cookie/localStorage
+</script>
+<script type="module" src="./main.js"></script>
+```
+
+---
+
 ## Komponen Base (Vue Components)
 
 Selain Web Components, library ini juga menyediakan **27 komponen Vue** yang bisa digunakan langsung di aplikasi Vue 3, Nuxt 3, dan framework apapun yang mendukung Vue.
@@ -70,7 +245,7 @@ Selain Web Components, library ini juga menyediakan **27 komponen Vue** yang bis
 | `DCodeSwitch` | Toggle switch |
 | `DCodeRadioCustom` | Radio button dengan opsi kustom |
 | `DCodeLabel` | Label untuk form |
-| `DCodeAutoComplete` | Input autocomplete dengan pencarian |
+| `DCodeAutoComplete` | Input autocomplete dengan pencarian dan fetch API otomatis |
 | `DCodeMultiSelect` | Dropdown multi-pilihan |
 | `DCodeDatePicker` | Date picker kalender |
 | `DCodeDateRangePicker` | Date range picker |
@@ -96,10 +271,6 @@ Selain Web Components, library ini juga menyediakan **27 komponen Vue** yang bis
 
 Cara paling ringan: import hanya komponen yang diperlukan.
 
-```bash
-npm install @gemafajarramadhan/dynamic-ui
-```
-
 ```vue
 <!-- MyForm.vue -->
 <script setup>
@@ -153,7 +324,12 @@ import DynamicUI from '@gemafajarramadhan/dynamic-ui'
 import '@gemafajarramadhan/dynamic-ui/style.css'
 
 const app = createApp(App)
-app.use(DynamicUI)  // Mendaftarkan semua DCode* komponen secara global
+
+app.use(DynamicUI, {
+  apiBaseUrl: import.meta.env.VITE_API_BASE_URL,
+  getAuthToken: () => localStorage.getItem('access_token'),
+})
+
 app.mount('#app')
 ```
 
@@ -180,7 +356,12 @@ import DynamicUI from '@gemafajarramadhan/dynamic-ui'
 import '@gemafajarramadhan/dynamic-ui/style.css'
 
 export default defineNuxtPlugin((nuxtApp) => {
-  nuxtApp.vueApp.use(DynamicUI)
+  const config = useRuntimeConfig()
+
+  nuxtApp.vueApp.use(DynamicUI, {
+    apiBaseUrl: config.public.apiBaseUrl,
+    getAuthToken: () => useCookie('access_token').value ?? null,
+  })
 })
 ```
 
@@ -198,6 +379,158 @@ Kemudian gunakan di page atau component manapun:
 
 ---
 
+## DCodeAutoComplete – Komponen dengan API
+
+`DCodeAutoComplete` adalah komponen autocomplete yang bisa **langsung fetch data dari API** menggunakan konfigurasi yang sudah di-set di host project.
+
+> ⚠️ Pastikan sudah mengatur [Konfigurasi API](#-konfigurasi-api-wajib) sebelum menggunakan fitur endpoint.
+
+### Perilaku Default
+
+- Setiap fetch otomatis mengirimkan `page=1` dan `perPage=100` sebagai query parameter default.
+- Nilai ini bisa di-override via prop `apiParams`.
+
+### Props Utama
+
+| Prop | Tipe | Default | Deskripsi |
+|------|------|---------|-----------|
+| `modelValue` | `any` | — | Value terpilih (v-model) |
+| `endpoint.apiUrl` | `string` | — | URL endpoint API (path atau full URL) |
+| `endpoint.apiMethod` | `string` | `'GET'` | HTTP method |
+| `apiParams` | `object` | `{}` | Query params tambahan (di-merge & bisa override default) |
+| `itemTitle` | `string\|Function` | `'name'` | Field nama tampilan dari tiap item |
+| `itemValue` | `string\|Function` | `'id'` | Field nilai dari tiap item |
+| `returnObject` | `boolean` | `false` | Jika `true`, v-model menyimpan objek penuh, bukan hanya `id` |
+| `clearable` | `boolean` | `false` | Tampilkan tombol hapus pilihan |
+| `disabled` | `boolean` | `false` | Nonaktifkan komponen |
+| `autoFetchOnOpen` | `boolean` | `true` | Fetch otomatis saat dropdown dibuka pertama kali |
+| `autoFetchOnMount` | `boolean` | `false` | Fetch otomatis saat komponen pertama kali di-mount |
+
+### Contoh Penggunaan
+
+#### Fetch dari API dengan URL langsung
+
+```vue
+<template>
+  <DCodeAutoComplete
+    v-model="selectedId"
+    label="Pilih Departemen"
+    :endpoint="{ apiUrl: '/api/master/departemen', apiMethod: 'GET' }"
+    item-title="nama"
+    item-value="id"
+    clearable
+  />
+</template>
+```
+
+> Request yang dikirim: `GET /api/master/departemen?page=1&perPage=100`
+> Base URL diambil otomatis dari konfigurasi host project (`apiBaseUrl`).
+
+#### Dengan Parameter Tambahan
+
+```vue
+<template>
+  <DCodeAutoComplete
+    v-model="selectedId"
+    label="Pilih Jabatan"
+    :endpoint="{ apiUrl: '/api/master/jabatan' }"
+    :apiParams="{ idDepartemen: selectedDeptId, isActive: true }"
+    item-title="namaJabatan"
+    item-value="idJabatan"
+  />
+</template>
+```
+
+> Request yang dikirim: `GET /api/master/jabatan?page=1&perPage=100&idDepartemen=5&isActive=true`
+
+#### Override Default Pagination
+
+```vue
+<template>
+  <!-- Ganti perPage menjadi 50 -->
+  <DCodeAutoComplete
+    v-model="selected"
+    label="Pilih Data"
+    :endpoint="{ apiUrl: '/api/data' }"
+    :apiParams="{ perPage: 50 }"
+    item-title="nama"
+    item-value="id"
+  />
+</template>
+```
+
+#### Dengan Data Statis (tanpa API)
+
+```vue
+<template>
+  <DCodeAutoComplete
+    v-model="selected"
+    label="Pilih Status"
+    :items="[
+      { id: 1, name: 'Aktif' },
+      { id: 0, name: 'Nonaktif' },
+    ]"
+    item-title="name"
+    item-value="id"
+  />
+</template>
+```
+
+#### Return Object Penuh
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const selectedUser = ref(null) // akan berisi { id: 1, name: 'John', email: '...' }
+</script>
+
+<template>
+  <DCodeAutoComplete
+    v-model="selectedUser"
+    label="Pilih User"
+    :endpoint="{ apiUrl: '/api/users' }"
+    item-title="name"
+    item-value="id"
+    return-object
+  />
+</template>
+```
+
+### Format Response API yang Diharapkan
+
+```json
+{
+  "status": true,
+  "data": {
+    "data": [
+      { "id": 1, "name": "Item A" },
+      { "id": 2, "name": "Item B" }
+    ]
+  }
+}
+```
+
+Atau format flat:
+
+```json
+{
+  "data": [
+    { "id": 1, "name": "Item A" }
+  ]
+}
+```
+
+Atau array langsung:
+
+```json
+[
+  { "id": 1, "name": "Item A" }
+]
+```
+
+---
+
 ## Web Components (Framework Agnostic)
 
 Untuk digunakan di **React, Angular, Svelte**, atau framework lainnya, gunakan mode Web Components.
@@ -252,13 +585,13 @@ import {
 
 ---
 
-## Cara Penggunaan
+## Penggunaan di Berbagai Framework
 
 ---
 
 ### 1. Vanilla HTML / JavaScript
 
-Cara paling sederhana. Import library dari CDN atau bundler, lalu gunakan custom element di HTML.
+Cara paling sederhana. Import library dari bundler, lalu gunakan custom element di HTML.
 
 ```html
 <!DOCTYPE html>
@@ -279,10 +612,17 @@ Cara paling sederhana. Import library dari CDN atau bundler, lalu gunakan custom
 
     <!-- Import library (registrasi Web Components otomatis) -->
     <script type="module">
-      import '@gemafajarramadhan/dynamic-ui';
+      import '@gemafajarramadhan/dynamic-ui'
+      import { setApiConfig } from '@gemafajarramadhan/dynamic-ui'
+
+      // ✅ Konfigurasi API dari host project
+      setApiConfig({
+        apiBaseUrl: 'https://api.example.com',
+        getAuthToken: () => localStorage.getItem('access_token'),
+      })
 
       // --- Setup Form ---
-      const form = document.querySelector('#myForm');
+      const form = document.querySelector('#myForm')
       form.config = {
         title: 'Registrasi User',
         sections: [
@@ -306,25 +646,25 @@ Cara paling sederhana. Import library dari CDN atau bundler, lalu gunakan custom
           },
         ],
         actions: [{ key: 'submit', label: 'Daftar', component: 'DCodeButton' }],
-      };
+      }
 
       form.addEventListener('submit', (e) => {
-        console.log('Data Form:', e.detail);
-      });
+        console.log('Data Form:', e.detail)
+      })
 
       // --- Setup DataTable ---
-      const table = document.querySelector('#myTable');
+      const table = document.querySelector('#myTable')
       table.config = {
         titleID: 'Daftar User',
         headers: [
           { text: 'Nama', value: 'name' },
           { text: 'Email', value: 'email' },
         ],
-      };
+      }
 
       table.addEventListener('action', (e) => {
-        console.log('Action:', e.detail);
-      });
+        console.log('Action:', e.detail)
+      })
     </script>
 
   </body>
@@ -333,7 +673,7 @@ Cara paling sederhana. Import library dari CDN atau bundler, lalu gunakan custom
 
 ---
 
-### 2. Vue 3
+### 2. Vue 3 (Web Components)
 
 Di Vue 3, Web Components bisa dipakai langsung seperti HTML element biasa. Gunakan `ref` untuk set properti objek.
 
@@ -366,12 +706,19 @@ export default defineConfig({
 // main.js
 import { createApp } from 'vue'
 import App from './App.vue'
-
-// Import library (registrasi Web Components)
-import '@gemafajarramadhan/dynamic-ui'
+import DynamicUI from '@gemafajarramadhan/dynamic-ui'
 import '@gemafajarramadhan/dynamic-ui/style.css'
 
-createApp(App).mount('#app')
+const app = createApp(App)
+
+// ✅ Konfigurasi API dari env host project
+app.use(DynamicUI, {
+  apiBaseUrl: import.meta.env.VITE_API_BASE_URL,
+  getAuthToken: () => localStorage.getItem('access_token'),
+  onUnauthorized: () => router.push('/login'),
+})
+
+app.mount('#app')
 ```
 
 #### Komponen Vue (`MyForm.vue`)
@@ -429,11 +776,17 @@ Di React, gunakan `useRef` dan `useEffect` untuk set properti DOM secara imperat
 import React from 'react'
 import ReactDOM from 'react-dom/client'
 import App from './App'
-
-// Import library (registrasi Web Components)
+import { setApiConfig } from '@gemafajarramadhan/dynamic-ui'
 import '@gemafajarramadhan/dynamic-ui'
 import '@gemafajarramadhan/dynamic-ui/style.css'
 
+// ✅ Konfigurasi API dari env host project
+setApiConfig({
+  apiBaseUrl: import.meta.env.VITE_API_BASE_URL,
+  getAuthToken: () => localStorage.getItem('access_token'),
+  onUnauthorized: () => { window.location.href = '/login' },
+})
+
 ReactDOM.createRoot(document.getElementById('root')).render(<App />)
 ```
 
@@ -562,6 +915,19 @@ declare global {
 
 Di Next.js dengan App Router, Web Components harus di-import di sisi klien (`'use client'`).
 
+#### Setup Konfigurasi API
+
+```ts
+// lib/dynamic-ui-config.ts
+import { setApiConfig } from '@gemafajarramadhan/dynamic-ui'
+
+setApiConfig({
+  apiBaseUrl: process.env.NEXT_PUBLIC_API_BASE_URL!,
+  getAuthToken: () => localStorage.getItem('access_token'),
+  onUnauthorized: () => { window.location.href = '/login' },
+})
+```
+
 #### Setup di Layout atau Client Component
 
 ```tsx
@@ -569,8 +935,7 @@ Di Next.js dengan App Router, Web Components harus di-import di sisi klien (`'us
 'use client'
 
 import { useEffect, useRef } from 'react'
-
-// Import hanya di sisi klien
+import '@/lib/dynamic-ui-config'
 import('@gemafajarramadhan/dynamic-ui')
 import '@gemafajarramadhan/dynamic-ui/style.css'
 
@@ -639,6 +1004,11 @@ export default function HomePage() {
 > const DynamicFormClient = dynamic(() => import('@/components/DynamicForm'), { ssr: false })
 > ```
 
+> File `.env.local` di host project:
+> ```env
+> NEXT_PUBLIC_API_BASE_URL=https://api.example.com
+> ```
+
 ---
 
 ### 5. Angular
@@ -666,16 +1036,30 @@ export class AppModule {}
 
 ```ts
 // main.ts
-import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'
-import { AppModule } from './app/app.module'
-
-// Import library (registrasi Web Components)
+import { setApiConfig } from '@gemafajarramadhan/dynamic-ui'
 import '@gemafajarramadhan/dynamic-ui'
 import '@gemafajarramadhan/dynamic-ui/style.css'
 
+// ✅ Konfigurasi API dari environment Angular
+import { environment } from './environments/environment'
+
+setApiConfig({
+  apiBaseUrl: environment.apiBaseUrl,
+  getAuthToken: () => localStorage.getItem('access_token'),
+  onUnauthorized: () => { window.location.href = '/login' },
+})
+
 platformBrowserDynamic().bootstrapModule(AppModule)
 ```
 
+> File `src/environments/environment.ts`:
+> ```ts
+> export const environment = {
+>   production: false,
+>   apiBaseUrl: 'https://api.example.com',
+> }
+> ```
+
 #### Komponen Angular (`dynamic-form.component.ts`)
 
 ```ts
@@ -761,11 +1145,18 @@ Buat file plugin dengan suffix `.client.ts` agar hanya dijalankan di sisi klien
 
 ```ts
 // plugins/dynamic-ui.client.ts
-import '@gemafajarramadhan/dynamic-ui'
+import DynamicUI from '@gemafajarramadhan/dynamic-ui'
 import '@gemafajarramadhan/dynamic-ui/style.css'
 
-export default defineNuxtPlugin(() => {
-  // Web Components sudah terdaftar saat import di atas
+export default defineNuxtPlugin((nuxtApp) => {
+  const config = useRuntimeConfig()
+
+  // ✅ Konfigurasi API dari runtimeConfig Nuxt (env host project)
+  nuxtApp.vueApp.use(DynamicUI, {
+    apiBaseUrl: config.public.apiBaseUrl,
+    getAuthToken: () => useCookie('access_token').value ?? null,
+    onUnauthorized: () => navigateTo('/login'),
+  })
 })
 ```
 
@@ -774,6 +1165,11 @@ export default defineNuxtPlugin(() => {
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
+  runtimeConfig: {
+    public: {
+      apiBaseUrl: process.env.VITE_API_BASE_URL, // set di .env
+    },
+  },
   vue: {
     compilerOptions: {
       // Arahkan Nuxt/Vue agar tidak menganggap element ini sebagai Vue component
@@ -912,6 +1308,8 @@ declare global {
   // Untuk global window registry
   interface Window {
     __MICRO_LOGIC_REGISTRY__?: Record<string, DynamicUI.LogicModule>
+    __MICRO_API_BASE_URL__?: string
+    __MICRO_AUTH_TOKEN__?: string
   }
 }