@vulform/vue/README.md

Vue components for VulForm contact form management

# @vulform/vue

Vue components and composables for VulForm integration. Build forms quickly with template-based components that handle validation, submission, and state management automatically.

## Installation

```bash
# Install with Bun (recommended)
bun add @vulform/vue

# Or with other package managers
npm install @vulform/vue
```

## Quick Start

```vue
<template>
  <VulForm
    template-id="your-template-id"
    api-key="vf_your_api_key"
    @success="handleSuccess"
    @error="handleError"
  />
</template>

<script setup>
import { VulForm } from '@vulform/vue';

const handleSuccess = response => {
  console.log('Form submitted!', response);
};

const handleError = error => {
  console.error('Submission failed:', error);
};
</script>
```

## Environment Variables

Set your API key in environment variables:

```bash
# Vite
VITE_VULFORM_API_KEY=vf_your_api_key

# Vue CLI
VUE_APP_VULFORM_API_KEY=vf_your_api_key
```

## Components

### VulForm

The main component that renders a complete form based on a template.

```vue
<template>
  <VulForm
    template-id="contact-form"
    :api-key="apiKey"
    api-url="/api/v1"
    theme="auto"
    class-name="my-form"
    :prefill="{ name: 'John Doe' }"
    @success="handleSuccess"
    @error="handleError"
    @validation-error="handleValidationError"
    @field-change="handleFieldChange"
    :enable-analytics="true"
    :spam-protection="true"
    :reset-on-success="true"
    :show-success-message="true"
  />
</template>

<script setup>
const apiKey = 'vf_abc123'; // Optional if set in env

const handleSuccess = response => console.log('Success!', response);
const handleError = error => console.error('Error:', error);
const handleValidationError = errors => console.log('Validation errors:', errors);
const handleFieldChange = (fieldName, value) => console.log('Field changed:', fieldName, value);
</script>
```

### Individual Components

```vue
<template>
  <!-- Custom loading state -->
  <FormLoader loading-state="custom" />

  <!-- Success message -->
  <FormSuccess message="Thank you!" @reset="resetForm" />

  <!-- Error display -->
  <FormError
    :error="{ code: 'NETWORK_ERROR', message: 'Connection failed' }"
    @retry="retrySubmission"
  />
</template>

<script setup>
import { FormLoader, FormSuccess, FormError } from '@vulform/vue';

const resetForm = () => {
  // Reset logic
};

const retrySubmission = () => {
  // Retry logic
};
</script>
```

## Composables

### useVulForm

Custom composable for building your own form components:

```vue
<template>
  <div v-if="loading">Loading...</div>
  <div v-else-if="error">Error: {{ error.message }}</div>
  <form v-else @submit.prevent="submitForm">
    <div v-for="field in template?.fields" :key="field.id">
      <input
        :type="field.type"
        :value="formData[field.name] || ''"
        @input="updateField(field.name, $event.target.value)"
      />
    </div>
    <button type="submit" :disabled="submitting">
      {{ submitting ? 'Sending...' : 'Submit' }}
    </button>
  </form>
</template>

<script setup>
import { useVulForm } from '@vulform/vue';

const {
  template,
  loading,
  error,
  submitting,
  formData,
  validationErrors,
  updateField,
  submitForm,
  resetForm,
} = useVulForm({
  templateId: 'contact-form',
  onSuccess: response => console.log('Success!'),
  onError: error => console.error('Error:', error),
});
</script>
```

## Styling

### CSS Variables

VulForm components use CSS variables that you can customize:

```css
.vulform-container {
  --vulform-primary: #3b82f6;
  --vulform-secondary: #1e40af;
  --vulform-background: #ffffff;
  --vulform-text: #374151;
  --vulform-border: #d1d5db;
  --vulform-border-radius: 0.5rem;
  --vulform-font-family: 'Inter', sans-serif;
  --vulform-font-size: 1rem;
  --vulform-spacing: 1rem;
}
```

### Custom Themes

```vue
<template>
  <VulForm template-id="contact-form" :theme="customTheme" />
</template>

<script setup>
const customTheme = {
  primaryColor: '#10b981',
  secondaryColor: '#059669',
  backgroundColor: '#f9fafb',
  textColor: '#111827',
  borderColor: '#d1d5db',
  borderRadius: '0.75rem',
  fontFamily: 'system-ui',
  fontSize: '1rem',
  spacing: '1.5rem',
};
</script>
```

### Tailwind CSS

VulForm works great with Tailwind CSS. Components include sensible default classes:

```vue
<template>
  <VulForm
    template-id="contact-form"
    class-name="max-w-2xl mx-auto p-6 bg-white rounded-lg shadow-lg"
  />
</template>
```

## Form Templates

Create form templates in the VulForm dashboard, then reference them by ID:

```vue
<template>
  <!-- Template ID from dashboard -->
  <VulForm template-id="cmc2o5rpm0007ju0d4et2g97d" />
</template>
```

Templates include:

- Field definitions (text, email, textarea, select, etc.)
- Validation rules
- Layout settings (vertical, horizontal, grid)
- Styling and themes
- Success/error messages

## Error Handling

```vue
<template>
  <VulForm template-id="contact-form" @error="handleError" />
</template>

<script setup>
import { VulFormError } from '@vulform/vue'

const handleError = (error: VulFormError) => {
  switch (error.code) {
    case 'MISSING_API_KEY':
      console.error('API key not configured')
      break
    case 'TEMPLATE_NOT_FOUND':
      console.error('Form template not found')
      break
    case 'RATE_LIMIT_EXCEEDED':
      console.error('Too many requests')
      break
    case 'NETWORK_ERROR':
      console.error('Network connection failed')
      break
    default:
      console.error('Unknown error:', error.message)
  }
}
</script>
```

## TypeScript

Full TypeScript support with type definitions:

```vue
<script setup lang="ts">
import type {
  VulFormProps,
  FormTemplate,
  FormField,
  SubmissionResponse,
  ValidationErrors,
} from '@vulform/vue';

const handleSuccess = (response: SubmissionResponse) => {
  console.log('Form submitted:', response.id);
};

const handleValidationError = (errors: ValidationErrors) => {
  Object.entries(errors).forEach(([field, error]) => {
    console.log(`${field}: ${error}`);
  });
};
</script>
```

## Vue 3 Composition API

Built specifically for Vue 3 with full Composition API support:

```vue
<script setup>
import { ref, computed, onMounted } from 'vue';
import { useVulForm } from '@vulform/vue';

// Reactive state
const selectedTemplate = ref('contact-form');

// Computed properties
const formConfig = computed(() => ({
  templateId: selectedTemplate.value,
  enableAnalytics: true,
  spamProtection: true,
}));

// Composable usage
const form = useVulForm(formConfig.value);

// Lifecycle
onMounted(() => {
  console.log('Form component mounted');
});
</script>
```

## 📦 CDN Usage

**Via unpkg.com:**

```html
<script src="https://unpkg.com/@vulform/vue@latest/dist/index.js"></script>
```

**Via jsDelivr:**

```html
<script src="https://cdn.jsdelivr.net/npm/@vulform/vue@latest/dist/index.js"></script>
```

> **Note:** For Vue applications, we recommend using the npm package for better tree-shaking and TypeScript support.

## License

MIT