RUMA form

RUMA form adalah sebuah engine dan library kuesioner dinamis berbasis React dan TypeScript yang dikembangkan khusus untuk merancang, menguji, dan mengisi instrumen pengumpulan data lapangan secara cerdas dan responsif. Pustaka ini mendukung validasi BPS (Badan Pusat Statistik), visualisasi wilayah Indonesia, lompatan logika (skip logic), kalkulasi otomatis, dan roster dinamis.

1. Cuplikan Layar Modul Utama

Berikut adalah modul antarmuka interaktif RUMA form:

A. Modul Pembuatan Kuesioner (Wizard Builder)

Halaman perancangan kuesioner secara grafis dan instan, dilengkapi visualizer multi-perangkat.

B. Modul Simulator Kuesioner (Playground)

Halaman pengujian interaktif untuk melihat rendering JSON schema, skip logic, dan validasi data secara instan.

C. Modul Dokumentasi & Sandbox API

Kamus isian parameter lengkap untuk mempelajari tipe field kuesioner beserta visualisasinya.

2. Fitur Utama

• Rendering Dinamis Berbasis JSON Schema: Mengubah skema input JSON kompleks (seksi, sub-bidang, dan roster) secara langsung menjadi elemen antarmuka web.
• Skip Logic & Conditional Visibility: Menyembunyikan atau menampilkan pertanyaan/seksi secara real-time berdasarkan jawaban pertanyaan sebelumnya.
• Computed Fields (Kalkulasi Otomatis): Menghitung akumulasi indeks, skor, umur, atau field matematis lainnya secara otomatis tanpa intervensi manual.
• Validasi Terpusat Kuesioner:
  • Error (Salah Isian) [Merah]: Menunjukkan kesalahan input format data.
  • Belum Terisi (Opsional) [Orange]: Peringatan kolom opsional kosong yang tidak menghambat proses submit.
  • Belum Terisi [Abu-abu]: Daftar global seluruh isian yang belum terisi di kuesioner.
  • Sudah Terisi [Hijau]: Jumlah isian yang berhasil diisi.
• Pemilihan Wilayah Administrasi Indonesia (indonesia-region): Dropdown berantai (Provinsi -> Kabupaten -> Kecamatan -> Desa) terintegrasi API publik yang dapat dibatasi pada wilayah tertentu (misal: hanya menampilkan wilayah Sumatera Utara).
• Kustomisasi Tema Warna Dinamis: Fitur pemilih warna kustom untuk mengubah warna utama (Primary), sekunder (Secondary), dan bar navigasi (Header Navbar) secara instan dan permanen.

3. Tech Stack

• Core: React 19.2.6, TypeScript 6.0.2
• Build Tool: Vite 8.0.12 (Mendukung Dual Mode: Web Simulator & NPM Library)
• Design & Icons: Vanilla CSS (HSL Variable Token System), Lucide React
• Select Engine: React Select (Searchable & Responsive dropdowns)

4. Getting Started & Instalasi

Pustaka ini dapat digunakan dengan dua cara: sebagai Aplikasi Simulator Lokal untuk merancang kuesioner, atau diinstal sebagai Pustaka NPM untuk diintegrasikan ke proyek front-end Anda.

Opsi A: Instalasi Sebagai Library NPM (Integrasi Proyek)

Jika Anda ingin merender kuesioner dinamis ini di proyek React/Vite Anda sendiri, pasang paketnya melalui NPM:

npm install @restusatrio11/ruma-form

Cara Penggunaan di Kode React:

import React from 'react';
import { FormRenderer } from '@restusatrio11/ruma-form';

// Objek JSON Schema kustom Anda
const skemaKuesioner = {
  id: "kuesioner_pendaftaran",
  title: "Pendaftaran Relawan",
  sections: [
    {
      id: "sec_identitas",
      title: "Blok I. Identitas",
      fields: [
        {
          id: "r101_nama",
          label: "Nama Lengkap",
          type: "text",
          validation: [{ type: "required", message: "Nama wajib diisi." }]
        }
      ]
    }
  ]
};

function App() {
  const handleComplete = (payload) => {
    console.log("Data hasil submit kuesioner:", payload);
    // Kirim payload hasil ke server database Anda
  };

  return (
    <div style={{ maxWidth: '800px', margin: '30px auto' }}>
      <FormRenderer
        schema={skemaKuesioner}
        draftKey="survey_draft_unique_key"
        onComplete={handleComplete}
      />
    </div>
  );
}

export default App;

Opsi B: Menjalankan Simulator Lokal (Development Mode)

Jika Anda ingin menjalankan aplikasi simulator lengkap di komputer lokal Anda:

1. Klon repositori ini ke komputer lokal Anda:

   git clone https://github.com/restusatrio11/form-engine-1200.git
   cd form-engine-1200

2. Instal semua dependensi proyek:

   npm install

3. Jalankan server pengembangan (development dev server):

   npm run dev

4. Buka browser Anda pada alamat http://localhost:5173/ untuk mencoba langsung modul Wizard dan Simulator.

5. API Dokumentasi Properti <FormRenderer />

Berikut adalah properti API yang didukung oleh komponen utama:

| Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | schema | FormDefinition | Ya | Berkas objek skema kuesioner hasil konfigurasi JSON. | | draftKey | string | Tidak | Kunci unik pemicu autosave di penyimpanan lokal browser. | | onStepChange | (id: string) => void | Tidak | Event ketika pengguna berpindah tab blok seksi kuesioner. | | onComplete | (payload: ResponsePayload) => void | Tidak | Callback yang dieksekusi saat kuesioner tervalidasi sukses & disubmit. |

6. Lisensi & Kontak

• License: MIT License
• Developer: Restu Satrio Pinanggih
• Repositori: https://github.com/restusatrio11/form-engine-1200
• Institusi: BPS Provinsi Sumatera Utara