@xniffing/form-engine

v0.2.10

Published

2 months ago

A Vue 3 form engine for building web forms

0High
0Medium
0Low

Form Engine

A powerful and flexible Vue 3 form engine for building dynamic web forms. This library provides a custom web component that can be easily integrated into any web application, regardless of the framework being used.

Features

🎯 Framework-agnostic (works with any web framework or vanilla JS)
🎨 Built with Vue 3 and TailwindCSS
📱 Fully responsive design
🔧 Supports multiple input types:
- Text
- Integer
- Date
- Boolean (checkbox)
- Single Selection (radio)
- Multi Selection (checkboxes)
- File Upload (with image preview)
- Sections
- Separators
🖼️ Image support for options and elements
✨ Real-time validation
🔄 Two-way data binding
📦 Easy to integrate
🎯 TypeScript support

Installation

NPM

npm install @xniffing/form-engine

Yarn

yarn add @xniffing/form-engine

PNPM

pnpm add @xniffing/form-engine

Usage

Basic Integration

HTML Integration

<!DOCTYPE html>
<html>
    <head>
        <script src="https://unpkg.com/vue@3/dist/vue.global.prod.js"></script>
        <script src="https://unpkg.com/@xniffing/form-engine"></script>
    </head>
    <body>
        <form-engine-builder></form-engine-builder>
    </body>
</html>

Module Integration

import FormEngine from '@xniffing/form-engine';
import '@xniffing/form-engine/style.css';
// The component is automatically registered as a web component

Updating Form Data

The form engine listens for the updateVModelData event to receive form data:

const formData = {
  "Form Version": {
    "Form Name": "My Form",
    "Elements": [
      {
        "GUID": "element1",
        "Name": "Full Name",
        "Description": "Enter your full name",
        "Is Mandatory": 1,
        "Type": "TEXT",
        "Value": ""
      }
      // ... more elements
    ]
  }
};

// Dispatch the event with form data
const event = new CustomEvent('updateVModelData', {
  detail: formData
});
window.dispatchEvent(event);

Form Data Structure

Element Types

The form engine supports the following element types:

TEXT: Text input
INTEGER: Number input
DATE: Date picker
BOOLEAN: Checkbox
SINGLESELECTION: Radio buttons
MULTISELECTION: Multiple checkboxes
UPLOAD: File upload with image preview
SECTION: Section header
SEPARATOR: Visual separator

Example Form Structure

{
  "Form Version": {
    "Form Name": "Sample Form",
    "Elements": [
      {
        "GUID": "unique-id-1",
        "Name": "Personal Information",
        "Description": "Please fill in your details",
        "Object": "SECTION",
        "Is Mandatory": 0
      },
      {
        "GUID": "unique-id-2",
        "Name": "Full Name",
        "Description": "Enter your full name",
        "Type": "TEXT",
        "Is Mandatory": 1,
        "Value": ""
      },
      {
        "GUID": "unique-id-3",
        "Name": "Age",
        "Type": "INTEGER",
        "Is Mandatory": 1,
        "Value": null
      },
      {
        "GUID": "unique-id-4",
        "Name": "Profile Picture",
        "Type": "UPLOAD",
        "Is Mandatory": 0,
        "FileTypes": ["image/*"]
      }
    ]
  }
}

Events

Input Events

The form engine emits the following events:

submit: Triggered when the form is submitted with valid data
error: Triggered when there's a validation error

Event Handling

const formEngine = document.querySelector('form-engine-builder');

formEngine.addEventListener('submit', (event) => {
  const formData = event.detail;
  console.log('Form submitted:', formData);
});

formEngine.addEventListener('error', (event) => {
  const errorMessage = event.detail;
  console.error('Form error:', errorMessage);
});

Styling

The form engine uses TailwindCSS for styling and provides a clean, modern interface out of the box. Custom styles can be applied by targeting the form engine's shadow DOM elements.

Development

Prerequisites

Node.js 18.x or higher
npm, yarn, or pnpm

Setup

# Clone the repository
git clone https://github.com/yourusername/form-engine.git

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

Scripts

npm run dev: Start development server
npm run build: Build for production
npm run preview: Preview production build
npm run version:patch: Bump patch version
npm run version:minor: Bump minor version
npm run version:major: Bump major version

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.