@skyworx/dynamic-ui

@gemafajarramadhan/dynamic-ui

Library Vue 3 component yang bisa digunakan di berbagai framework (Vue, React, Angular, Svelte, dll.) untuk membuat Dynamic Form dan DataTable otomatis dari JSON schema, sekaligus menyediakan komponen UI yang kaya fitur.

Daftar Isi

• Fitur
• Instalasi
• ⚡ Konfigurasi API (WAJIB)
  • Vue 3
  • Nuxt 3
  • React / Next.js
  • Angular
  • Vanilla JS (window global)
• Komponen Base (Vue Components)
  • Daftar Komponen
  • Penggunaan di Vue 3 (Import Per Komponen)
  • Penggunaan di Vue 3 (Global Plugin)
  • Penggunaan di Nuxt 3
• DCodeDataTable – Tabel Dinamis
  • Props Utama
  • Pola 1 — fetchHandler (MFE)
  • Pola 2 — Static Data
  • Pola 3 — Realtime Socket
  • Format Response
  • Expose Methods
• DCodeAutoComplete – Komponen dengan API
• Web Components (Framework Agnostic)
  • API Referensi Web Components
  • Logic Registry API
• Penggunaan di Berbagai Framework
  • Vanilla HTML / JavaScript
  • Vue 3 (Web Components)
  • React
  • Next.js (App Router)
  • Angular
  • Nuxt 3 (Web Components)
• Custom Logic Registry
• TypeScript Support

Fitur

• 🧩 Web Components – Dapat digunakan di framework apapun (React, Vue, Angular, Svelte, dll.) atau di HTML biasa.
• 📋 AutoLayoutForm – Generate form otomatis dari JSON schema dengan validasi dan konfigurasi fleksibel.
• 📊 AutoLayoutDatatable – Generate tabel dengan pagination, sorting, filtering, dan action button dari JSON.
• 🔌 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.

Instalasi

# npm
npm install @gemafajarramadhan/dynamic-ui

# yarn
yarn add @gemafajarramadhan/dynamic-ui

# pnpm
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:

Konfigurasi API di Vue 3

Cara paling direkomendasikan: lewatkan config saat app.use(), atau gunakan setApiConfig secara langsung. Hal ini sangat penting agar request API dari komponen (seperti DCodeAutoComplete) mem-bypass native fetch bawaan dan menggunakan instance HTTP (seperti Axios) milik project host Anda. Dengan begitu, request otomatis melewati interceptor (untuk inject token) dan mengarah ke base URL yang tepat saat di production.

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import DynamicUI, { setApiConfig } from '@gemafajarramadhan/dynamic-ui'
import '@gemafajarramadhan/dynamic-ui/style.css'

// Contoh import instance Axios / useApi dari host project Anda
import axiosInstance from './plugins/axios' 
// import { useApi } from './composables/useApi' 

const app = createApp(App)

// OPSI 1: Konfigurasi memanggil fungsi (Bisa dipanggil di luar instalasi plugin)
setApiConfig({
  // WAJIB: Bypass fetch bawaan, gunakan axios dari project host
  apiClient: async (url, method, data) => {
    return axiosInstance({ url, method, data })
    /* ATAU MENGGUNAKAN useApi bawaan project host
    const { apiUrl } = useApi()
    return apiUrl(url, method || 'GET', data, { disableGlobalLoading: true })
    */
  },
  
  // Base URL API dari env HOST project
  apiBaseUrl: import.meta.env.VITE_API_BASE_URL,
  
  // (Opsional jika apiClient sudah memiliki interceptor token)
  getAuthToken: () => localStorage.getItem('access_token'),
})

// OPSI 2: Lewatkan pada saat app.use (Berlaku jika tidak menggunakan setApiConfig di atas)
app.use(DynamicUI, {
  apiClient: async (url, method, data) => axiosInstance({ url, method, data }),
  apiBaseUrl: import.meta.env.VITE_API_BASE_URL,
})

app.mount('#app')

File .env di host project Anda:

VITE_API_BASE_URL=https://api.example.com

Konfigurasi API di Nuxt 3

// 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:

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).

// 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:

// 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:

NEXT_PUBLIC_API_BASE_URL=https://api.example.com

Konfigurasi API di Angular

// 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:

<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.

Daftar Komponen

Penggunaan di Vue 3 (Import Per Komponen)

Cara paling ringan: import hanya komponen yang diperlukan.

<!-- MyForm.vue -->
<script setup>
import { DCodeTextField, DCodeButton } from '@gemafajarramadhan/dynamic-ui'
import '@gemafajarramadhan/dynamic-ui/style.css'
</script>

<template>
  <form>
    <DCodeTextField
      v-model="form.name"
      label="Nama Lengkap"
      placeholder="Masukkan nama..."
      :clearable="true"
    />

    <DCodeTextField
      v-model="form.email"
      label="Email"
      valueType="email"
      placeholder="nama@email.com"
    />

    <DCodeButton
      text="Simpan"
      variant="default"
      bgColor="primary"
      type="submit"
    />
  </form>
</template>

<script setup>
import { reactive } from 'vue'

const form = reactive({ name: '', email: '' })
</script>

Penggunaan di Vue 3 (Global Plugin)

Install semua komponen sekaligus agar bisa digunakan di mana saja tanpa import per file.

// 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, {
  apiBaseUrl: import.meta.env.VITE_API_BASE_URL,
  getAuthToken: () => localStorage.getItem('access_token'),
})

app.mount('#app')

Setelah itu, semua komponen bisa digunakan tanpa import di setiap file:

<!-- Tidak perlu import lagi! -->
<template>
  <DCodeTextField v-model="name" label="Nama" />
  <DCodeButton text="Submit" />
  <DCodeDatePicker v-model="date" label="Tanggal" />
</template>

Penggunaan di Nuxt 3 (Vue Components)

Buat plugin Nuxt untuk mendaftarkan semua komponen secara global:

// 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, {
    apiBaseUrl: config.public.apiBaseUrl,
    getAuthToken: () => useCookie('access_token').value ?? null,
  })
})

Kemudian gunakan di page atau component manapun:

<!-- pages/index.vue -->
<template>
  <div>
    <DCodeTextField v-model="search" label="Pencarian" :clearable="true" />
    <DCodeButton text="Cari" variant="default" />
  </div>
</template>

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

Events

Pola 1 — fetchHandler ⭐ Disarankan untuk MFE

Consumer kontrol penuh HTTP. Component tidak hit endpoint sama sekali — cocok untuk menghindari error 401.

<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.

<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.

<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:

{ "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)

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)
 // Reactive nilai filter saat ini

<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.

⚠️ Pastikan sudah mengatur Konfigurasi API 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

Contoh Penggunaan

Fetch dari API dengan URL langsung

<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

<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

<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)

<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

<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

{
  "status": true,
  "data": {
    "data": [
      { "id": 1, "name": "Item A" },
      { "id": 2, "name": "Item B" }
    ]
  }
}

Atau format flat:

{
  "data": [
    { "id": 1, "name": "Item A" }
  ]
}

Atau array langsung:

[
  { "id": 1, "name": "Item A" }
]

Web Components (Framework Agnostic)

Untuk digunakan di React, Angular, Svelte, atau framework lainnya, gunakan mode Web Components.

API Referensi Web Components

Web Components

Setelah library di-import, dua custom element berikut akan terdaftar secara global:

Properties (set via JavaScript/DOM)

Karena Web Components menerima objek JavaScript (bukan string HTML attribute), set properti ini secara imperatif via DOM atau ref:

Events

Logic Registry API

Digunakan untuk menyuntikkan business logic dari aplikasi host ke dalam komponen.

import {
  registerLogic,
  unregisterLogic,
  getLogicModule
} from '@gemafajarramadhan/dynamic-ui'

Penggunaan di Berbagai Framework

1. Vanilla HTML / JavaScript

Cara paling sederhana. Import library dari bundler, lalu gunakan custom element di HTML.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Dynamic UI</title>
    <!-- Import style -->
    <link rel="stylesheet" href="./node_modules/@gemafajarramadhan/dynamic-ui/dist/style.css" />
  </head>
  <body>

    <!-- Dynamic Form -->
    <micro-dynamic-form id="myForm"></micro-dynamic-form>

    <!-- Dynamic DataTable (AutoLayout version) -->
    <micro-dynamic-datatable id="myAutoTable"></micro-dynamic-datatable>

    <!-- Base DataTable (Stand-alone version) -->
    <micro-data-table id="myBaseTable"></micro-data-table>

    <!-- Import library (registrasi Web Components otomatis) -->
    <script type="module">
      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')
      form.config = {
        title: 'Registrasi User',
        sections: [
          {
            title: 'Info Pribadi',
            fields: [
              {
                key: 'name',
                label: 'Nama Lengkap',
                model: 'fullName',
                component: 'DCodeTextField',
              },
              {
                key: 'email',
                label: 'Email',
                model: 'email',
                component: 'DCodeTextField',
                props: { type: 'email' },
              },
            ],
          },
        ],
        actions: [{ key: 'submit', label: 'Daftar', component: 'DCodeButton' }],
      }

      form.addEventListener('submit', (e) => {
        
      })

      // --- Setup DataTable ---
      const autoTable = document.querySelector('#myAutoTable')
      autoTable.config = {
        titleID: 'Daftar User',
        headers: [
          { text: 'Nama', value: 'name' },
          { text: 'Email', value: 'email' },
        ],
      }

      autoTable.addEventListener('action', (e) => {
        
      })

      // --- Setup Base MicroDataTable ---
      const baseTable = document.querySelector('#myBaseTable')
      // Untuk MicroDataTable (base component), Anda bisa mengirimkan prop langsung:
      baseTable.columns = [
        { key: 'name', label: 'Nama', sortable: true },
        { key: 'email', label: 'Email' }
      ]
      // Memberikan data secara statis
      baseTable.data = [
        { name: 'John Doe', email: 'john@example.com' },
        { name: 'Jane Smith', email: 'jane@example.com' }
      ]
      
      // Atau bisa diset melalui API:
      // baseTable.apiUrl = '/api/users'
      // baseTable.apiMethod = 'GET'
    </script>

  </body>
</html>

2. Vue 3 (Web Components)

Di Vue 3, Web Components bisa dipakai langsung seperti HTML element biasa. Gunakan ref untuk set properti objek.

Konfigurasi Vite

Agar Vue tidak menganggap micro-dynamic-* sebagai Vue component yang belum terdaftar, tambahkan isCustomElement di vite.config.js:

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          // Semua element yang dimulai dengan 'micro-' dianggap custom element
          isCustomElement: (tag) => tag.startsWith('micro-'),
        },
      },
    }),
  ],
})

Entry Point (main.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)

// ✅ 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)

<script setup>
import { ref, onMounted } from 'vue'

const formRef = ref(null)

const formConfig = {
  title: 'Form User',
  sections: [
    {
      fields: [
        {
          key: 'username',
          label: 'Username',
          model: 'username',
          component: 'DCodeTextField',
        },
      ],
    },
  ],
  actions: [{ key: 'save', label: 'Simpan', component: 'DCodeButton' }],
}

onMounted(() => {
  if (formRef.value) {
    // Set config via DOM property (bukan attribute)
    formRef.value.config = formConfig

    formRef.value.addEventListener('submit', (e) => {
      
    })
  }
})
</script>

<template>
  <micro-dynamic-form ref="formRef" />
</template>

3. React

Di React, gunakan useRef dan useEffect untuk set properti DOM secara imperatif karena React tidak meneruskan objek langsung ke Web Component attributes.

Entry Point (main.jsx)

// main.jsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
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 />)

Dynamic Form Component

// components/DynamicForm.jsx
import React, { useEffect, useRef } from 'react'

const formConfig = {
  title: 'Form via React',
  sections: [
    {
      fields: [
        {
          key: 'username',
          label: 'Username',
          model: 'username',
          component: 'DCodeTextField',
        },
        {
          key: 'email',
          label: 'Email',
          model: 'email',
          component: 'DCodeTextField',
          props: { type: 'email' },
        },
      ],
    },
  ],
  actions: [{ key: 'submit', label: 'Kirim', component: 'DCodeButton' }],
}

export default function DynamicForm() {
  const formRef = useRef(null)

  useEffect(() => {
    const el = formRef.current
    if (!el) return

    // Set config sebagai DOM property
    el.config = formConfig

    const handleSubmit = (event) => {
      
    }

    el.addEventListener('submit', handleSubmit)

    // Cleanup listener saat unmount
    return () => {
      el.removeEventListener('submit', handleSubmit)
    }
  }, [])

  return <micro-dynamic-form ref={formRef}></micro-dynamic-form>
}

Dynamic DataTable Component

// components/DynamicTable.jsx
import React, { useEffect, useRef } from 'react'

const tableConfig = {
  titleID: 'Daftar User',
  headers: [
    { text: 'Nama', value: 'name' },
    { text: 'Email', value: 'email' },
    { text: 'Status', value: 'status' },
  ],
}

export default function DynamicTable() {
  const tableRef = useRef(null)

  useEffect(() => {
    const el = tableRef.current
    if (!el) return

    el.config = tableConfig

    const handleAction = (event) => {
      
    }

    el.addEventListener('action', handleAction)

    return () => {
      el.removeEventListener('action', handleAction)
    }
  }, [])

  return <micro-dynamic-datatable ref={tableRef}></micro-dynamic-datatable>
}

TypeScript + React

Tambahkan deklarasi tipe agar JSX tidak mengeluh tentang custom element:

// src/types/dynamic-ui.d.ts
import React from 'react'

declare global {
  namespace JSX {
    interface IntrinsicElements {
      'micro-dynamic-form': React.DetailedHTMLProps<
        React.HTMLAttributes<HTMLElement>,
        HTMLElement
      >
      'micro-dynamic-datatable': React.DetailedHTMLProps<
        React.HTMLAttributes<HTMLElement>,
        HTMLElement
      >
    }
  }
}

4. Next.js (App Router)

Di Next.js dengan App Router, Web Components harus di-import di sisi klien ('use client').

Setup Konfigurasi API

// 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

// components/DynamicForm.tsx
'use client'

import { useEffect, useRef } from 'react'
import '@/lib/dynamic-ui-config'
import('@gemafajarramadhan/dynamic-ui')
import '@gemafajarramadhan/dynamic-ui/style.css'

const formConfig = {
  title: 'Form Next.js',
  sections: [
    {
      fields: [
        {
          key: 'name',
          label: 'Nama',
          model: 'name',
          component: 'DCodeTextField',
        },
      ],
    },
  ],
  actions: [{ key: 'submit', label: 'Submit', component: 'DCodeButton' }],
}

export default function DynamicFormClient() {
  const formRef = useRef<HTMLElement>(null)

  useEffect(() => {
    const el = formRef.current
    if (!el) return

    ;(el as any).config = formConfig

    const handleSubmit = (event: Event) => {
      const customEvent = event as CustomEvent
      
    }

    el.addEventListener('submit', handleSubmit)
    return () => el.removeEventListener('submit', handleSubmit)
  }, [])

  return (
    // @ts-ignore – custom element tidak dikenal TypeScript secara default
    <micro-dynamic-form ref={formRef}></micro-dynamic-form>
  )
}

Penggunaan di Page

// app/page.tsx
import DynamicFormClient from '@/components/DynamicForm'

export default function HomePage() {
  return (
    <main>
      <h1>Dynamic Form</h1>
      <DynamicFormClient />
    </main>
  )
}

Catatan: Gunakan dynamic() dari next/dynamic dengan { ssr: false } jika terjadi error SSR.

import dynamic from 'next/dynamic'
const DynamicFormClient = dynamic(() => import('@/components/DynamicForm'), { ssr: false })

File .env.local di host project:

NEXT_PUBLIC_API_BASE_URL=https://api.example.com

5. Angular

Di Angular, tambahkan CUSTOM_ELEMENTS_SCHEMA agar Angular tidak melempar error pada custom element yang tidak dikenali.

app.module.ts (Module-based)

// app.module.ts
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'
import { BrowserModule } from '@angular/platform-browser'
import { AppComponent } from './app.component'

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA], // <-- Wajib ditambahkan
  bootstrap: [AppComponent],
})
export class AppModule {}

main.ts

// main.ts
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:

export const environment = {
  production: false,
  apiBaseUrl: 'https://api.example.com',
}

Komponen Angular (dynamic-form.component.ts)

// dynamic-form.component.ts
import {
  Component,
  OnInit,
  AfterViewInit,
  ViewChild,
  ElementRef,
} from '@angular/core'

@Component({
  selector: 'app-dynamic-form',
  template: `<micro-dynamic-form #formEl></micro-dynamic-form>`,
})
export class DynamicFormComponent implements AfterViewInit {
  @ViewChild('formEl') formRef!: ElementRef

  private formConfig = {
    title: 'Form Angular',
    sections: [
      {
        fields: [
          {
            key: 'username',
            label: 'Username',
            model: 'username',
            component: 'DCodeTextField',
          },
        ],
      },
    ],
    actions: [{ key: 'submit', label: 'Simpan', component: 'DCodeButton' }],
  }

  ngAfterViewInit() {
    const el = this.formRef.nativeElement

    // Set config via DOM property
    el.config = this.formConfig

    el.addEventListener('submit', (event: CustomEvent) => {
      
    })
  }
}

Angular Standalone (Angular 17+)

// app.component.ts
import { Component, AfterViewInit, ViewChild, ElementRef } from '@angular/core'
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'

@Component({
  selector: 'app-root',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `<micro-dynamic-form #formEl></micro-dynamic-form>`,
})
export class AppComponent implements AfterViewInit {
  @ViewChild('formEl') formRef!: ElementRef

  ngAfterViewInit() {
    const el = this.formRef.nativeElement
    el.config = { /* config Anda di sini */ }
    el.addEventListener('submit', (e: CustomEvent) => 
  }
}

6. Nuxt 3

Di Nuxt 3, gunakan plugin untuk mendaftarkan Web Components dan tandai sebagai custom element.

Plugin (plugins/dynamic-ui.client.ts)

Buat file plugin dengan suffix .client.ts agar hanya dijalankan di sisi klien (browser):

// plugins/dynamic-ui.client.ts
import DynamicUI from '@gemafajarramadhan/dynamic-ui'
import '@gemafajarramadhan/dynamic-ui/style.css'

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'),
  })
})

Konfigurasi Nuxt (nuxt.config.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
      isCustomElement: (tag: string) => tag.startsWith('micro-'),
    },
  },
})

Penggunaan di Page atau Component

<!-- pages/index.vue -->
<script setup>
import { ref, onMounted } from 'vue'

const formRef = ref(null)

const formConfig = {
  title: 'Form Nuxt',
  sections: [
    {
      fields: [
        {
          key: 'name',
          label: 'Nama',
          model: 'name',
          component: 'DCodeTextField',
        },
      ],
    },
  ],
  actions: [{ key: 'submit', label: 'Submit', component: 'DCodeButton' }],
}

onMounted(() => {
  if (formRef.value) {
    formRef.value.config = formConfig
    formRef.value.addEventListener('submit', (e) => {
      
    })
  }
})
</script>

<template>
  <div>
    <h1>Halaman Dynamic Form</h1>
    <!-- Gunakan ClientOnly agar tidak error saat SSR -->
    <ClientOnly>
      <micro-dynamic-form ref="formRef" />
    </ClientOnly>
  </div>
</template>

Custom Logic Registry

Library menyediakan Logic Registry agar aplikasi host dapat menyuntikkan business logic ke dalam komponen tanpa memodifikasi library.

Option A: via window (sebelum library dimuat)

window.__MICRO_LOGIC_REGISTRY__ = {
  'user-management': {
    onReady(context) {
      
    },
    handleAction(action, payload) {
      if (action === 'delete') {
        // Tampilkan modal konfirmasi
        return true // intercept action
      }
    },
  },
}

Option B: via fungsi registerLogic (setelah import library)

import {
  registerLogic,
  unregisterLogic,
} from '@gemafajarramadhan/dynamic-ui'

registerLogic('user-management', {
  onReady(context) {
    
  },
  handleAction(action, payload) {
    
  },
})

// Untuk menghapus logic saat komponen unmount:
// unregisterLogic('user-management')

Interface LogicModule

interface LogicModule {
  onReady?: (context: Record<string, any>) => void
  handleAction?: (action: string, payload: any) => boolean | void
}

TypeScript Support

Untuk menambahkan type yang benar pada semua framework, buat file deklarasi global:

// src/types/dynamic-ui.d.ts

declare namespace DynamicUI {
  interface LogicModule {
    onReady?: (context: Record<string, any>) => void
    handleAction?: (action: string, payload: any) => boolean | void
  }
}

// Deklarasi untuk custom element di JSX (React / Next.js)
declare global {
  namespace JSX {
    interface IntrinsicElements {
      'micro-dynamic-form': any
      'micro-dynamic-datatable': any
    }
  }

  // Untuk global window registry
  interface Window {
    __MICRO_LOGIC_REGISTRY__?: Record<string, DynamicUI.LogicModule>
    __MICRO_API_BASE_URL__?: string
    __MICRO_AUTH_TOKEN__?: string
  }
}

export {}

Referensi Props Komponen

Berikut adalah dokumentasi lengkap props untuk setiap komponen yang tersedia.

DataTable

Komponen tabel data yang mendukung mode API (fetch otomatis) maupun data statis, dengan pagination, sorting, filtering, dan action button.

<template>
  <!-- Mode API -->
  <DataTable
    api-url="/api/users"
    api-method="POST"
    :columns="[
      { key: 'name', label: 'Nama', sortable: true },
      { key: 'email', label: 'Email' },
    ]"
    :per-page="25"
  />

  <!-- Mode data statis -->
  <DataTable
    :data="myData"
    :columns="columns"
  />
</template>

DCodeButton

Tombol dengan berbagai variant, warna kustom, ikon Lucide, dan tooltip.

<template>
  <DCodeButton text="Simpan" icon="Save" variant="default" />
  <DCodeButton text="Hapus" icon="Trash2" variant="destructive" tooltip="Hapus data ini" />
  <DCodeButton text="Submit" type="submit" :disabled="isLoading" />
</template>

DCodeTextField

Input teks dengan banyak fitur: filter karakter, transformasi case, clearable, password toggle.

<template>
  <DCodeTextField
    v-model="form.name"
    label="Nama Lengkap"
    placeholder="Masukkan nama..."
    text-case="titlecase"
    clearable
  />
  <DCodeTextField
    v-model="form.email"
    label="Email"
    value-type="email"
    :error="errors.email"
  />
  <DCodeTextField
    v-model="form.password"
    label="Password"
    value-type="password"
  />
</template>

DCodeTextarea

Textarea dengan karakter counter, filter, dan transformasi case.

<template>
  <DCodeTextarea
    v-model="form.description"
    label="Deskripsi"
    placeholder="Masukkan deskripsi..."
    :show-char-count="true"
    maxlength="500"
  />
</template>

DCodeAutoComplete

Dropdown autocomplete dengan fetch API otomatis dan pencarian.

<template>
  <DCodeAutoComplete
    v-model="form.departemenId"
    label="Departemen"
    :endpoint="{ apiUrl: '/api/master/departemen' }"
    item-title="nama"
    item-value="id"
    clearable
  />
</template>

DCodeInfiniteAutoComplete

Autocomplete dengan pagination infinite scroll (load more saat scroll ke bawah).

<template>
  <DCodeInfiniteAutoComplete
    v-model="form.userId"
    label="Pilih User"
    :endpoint="{ apiUrl: '/api/users', apiMethod: 'GET' }"
    item-title="fullName"
    item-value="id"
    :page-size="15"
  />
</template>

DCodeMultiSelect

Dropdown multi-pilihan dengan chip tags dan search.

<template>
  <DCodeMultiSelect
    v-model="form.tags"
    label="Tags"
    :items="availableTags"
    item-title="name"
    item-value="id"
    :max-selected="5"
    searchable
  />
</template>

DCodeDatePicker

Date picker atau date range picker dengan berbagai format.

<template>
  <!-- Single date -->
  <DCodeDatePicker
    v-model="form.tanggal"
    label="Tanggal Lahir"
    :range="false"
    display-format="dd MMMM yyyy"
    locale="id"
  />

  <!-- Date range -->
  <DCodeDatePicker
    v-model="form.periode"
    label="Periode"
    :range="true"
  />
</template>

DCodeCurrencyField

Input angka dengan format mata uang otomatis.

<template>
  <DCodeCurrencyField
    v-model="form.harga"
    label="Harga"
    currency="IDR"
    clearable
    :error="errors.harga"
  />
</template>

DCodeCheckbox

Checkbox dengan label dan dukungan indeterminate state.

Gunakan attr label untuk teks di samping checkbox.

<template>
  <DCodeCheckbox
    v-model="form.setuju"
    label="Saya setuju dengan syarat & ketentuan"
    required
  />
</template>

DCodeSwitch

Toggle switch dengan berbagai ukuran, warna, dan tooltip.

<template>
  <DCodeSwitch
    v-model="form.isActive"
    label="Status Aktif"
    color="success"
    size="medium"
    :show-tooltip="true"
  />
</template>

DCodeRadio

Grup radio button yang bisa fetch opsi dari API.

<template>
  <!-- Dengan opsi statis -->
  <DCodeRadio
    v-model="form.gender"
    :options="[
      { id: 'L', name: 'Laki-laki' },
      { id: 'P', name: 'Perempuan' },
    ]"
  />

  <!-- Dengan API -->
  <DCodeRadio
    v-model="form.statusId"
    api-url="/api/master/status"
    label="nama"
    model="id"
  />
</template>

DCodeRadioCustom

Radio button dengan tampilan card kustom dan ikon.

<template>
  <DCodeRadioCustom
    v-model="form.plan"
    :options="[
      { id: 'basic', name: 'Basic', icon: 'Star' },
      { id: 'pro', name: 'Pro', icon: 'Zap' },
    ]"
    label="name"
    model="id"
  />
</template>

DCodeOtpInput

Input OTP digit-per-digit dengan submit otomatis ke API.

Events: complete (OTP penuh), success, error, loading

<template>
  <DCodeOtpInput
    v-model="otp"
    :total-input="6"
    label="Kode OTP"
    :endpoint="{ apiUrl: '/api/auth/verify-otp', apiMethod: 'POST' }"
    @complete="handleOtpComplete"
  />
</template>

DCodeFileField

Upload file dengan validasi tipe & ukuran, preview, dan upload ke API.

<template>
  <DCodeFileField
    v-model="form.dokumen"
    label="Upload Dokumen"
    allowed-types="pdf,doc,docx"
    :max-size-mb="10"
    :endpoint="{ apiUrl: '/api/upload', apiMethod: 'POST' }"
    @uploaded="handleUploaded"
    @error="handleError"
  />
</template>

DCodeImageField

Upload gambar dengan crop/resize dialog terintegrasi.

<template>
  <DCodeImageField
    v-model="form.foto"
    label="Foto Profil"
    :aspect-ratio="1"
    :output-width="300"
    :output-height="300"
    :max-size-m