# @vulform/astro

Astro components for VulForm contact form management with server-side rendering and progressive enhancement.

## Installation

```bash
npm install @vulform/astro
# or
yarn add @vulform/astro
# or
pnpm add @vulform/astro
# or
bun add @vulform/astro
```

## Setup

### 1. Add the Integration

Add the VulForm integration to your `astro.config.mjs`:

```js
import { defineConfig } from 'astro/config';
import { VulFormIntegration } from '@vulform/astro';

export default defineConfig({
  integrations: [
    VulFormIntegration({
      apiKey: process.env.VULFORM_API_KEY, // Optional: set globally
      apiUrl: 'https://api.vulform.dev', // Optional: custom API URL
      debug: false, // Optional: enable debug mode
    }),
  ],
});
```

### 2. Environment Variables

Create a `.env` file in your project root:

```env
VULFORM_API_KEY=your_api_key_here
```

## Usage

### Basic Usage

```astro
---
import { VulForm } from '@vulform/astro';
---

<VulForm
  templateId="your-template-id"
  apiKey={process.env.VULFORM_API_KEY}
/>
```

### Advanced Usage

```astro
---
import { VulForm } from '@vulform/astro';

const formConfig = {
  templateId: "your-template-id",
  apiKey: process.env.VULFORM_API_KEY,
  theme: "auto",
  prefill: {
    name: "John Doe",
    email: "john@example.com"
  },
  enableAnalytics: true,
  spamProtection: true,
  loadingState: "skeleton",
  resetOnSuccess: true,
  showSuccessMessage: true
};
---

<VulForm
  {...formConfig}
  class="max-w-2xl"
  style={{ backgroundColor: '#f9fafb' }}
/>
```

### Custom Styling

```astro
---
import { VulForm } from '@vulform/astro';
---

<VulForm
  templateId="your-template-id"
  class="custom-form-class"
/>

<style>
  .custom-form-class {
    max-width: 600px;
    margin: 0 auto;
    padding: 2rem;
    background: white;
    border-radius: 0.5rem;
    box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
  }

  .custom-form-class :global(.vulform-input) {
    border-radius: 0.75rem;
    padding: 1rem;
  }

  .custom-form-class :global(.vulform-submit-button) {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    border: none;
    border-radius: 0.75rem;
    padding: 1rem 2rem;
    font-weight: 600;
    text-transform: uppercase;
    letter-spacing: 0.05em;
  }
</style>
```

## Props

| Prop                 | Type                                   | Default                       | Description                            |
| -------------------- | -------------------------------------- | ----------------------------- | -------------------------------------- |
| `templateId`         | `string`                               | **Required**                  | Your VulForm template ID               |
| `apiKey`             | `string`                               | `process.env.VULFORM_API_KEY` | Your VulForm API key                   |
| `apiUrl`             | `string`                               | `'https://api.vulform.dev'`   | VulForm API URL                        |
| `theme`              | `'auto' \| 'light' \| 'dark'`          | `'auto'`                      | Form theme                             |
| `class`              | `string`                               | `''`                          | CSS class for the form container       |
| `style`              | `object`                               | `{}`                          | Inline styles for the form container   |
| `prefill`            | `object`                               | `{}`                          | Pre-fill form fields                   |
| `enableAnalytics`    | `boolean`                              | `true`                        | Enable form analytics                  |
| `spamProtection`     | `boolean`                              | `true`                        | Enable spam protection                 |
| `loadingState`       | `'default' \| 'skeleton' \| 'spinner'` | `'default'`                   | Loading state style                    |
| `resetOnSuccess`     | `boolean`                              | `true`                        | Reset form after successful submission |
| `showSuccessMessage` | `boolean`                              | `true`                        | Show success message after submission  |
| `autoRedirect`       | `boolean`                              | `false`                       | Auto-redirect after submission         |

## Server-Side Rendering (SSR)

VulForm Astro components are designed to work with both static site generation (SSG) and server-side rendering (SSR). The components render a loading state on the server and progressively enhance with JavaScript on the client.

### SSG (Static Site Generation)

```astro
---
// pages/contact.astro
import { VulForm } from '@vulform/astro';
---

<html>
  <head>
    <title>Contact Us</title>
  </head>
  <body>
    <main>
      <h1>Contact Us</h1>
      <VulForm templateId="contact-form" />
    </main>
  </body>
</html>
```

### SSR (Server-Side Rendering)

```astro
---
// pages/contact.astro
import { VulForm } from '@vulform/astro';

// Access form data on the server
const formData = Astro.url.searchParams.get('form-data');
---

<html>
  <head>
    <title>Contact Us</title>
  </head>
  <body>
    <main>
      <h1>Contact Us</h1>
      <VulForm
        templateId="contact-form"
        prefill={formData ? JSON.parse(formData) : {}}
      />
    </main>
  </body>
</html>
```

## Progressive Enhancement

The Astro component uses progressive enhancement to provide a great user experience:

1. **Server-rendered HTML**: Form renders immediately with proper semantic HTML
2. **No-JS fallback**: Form works without JavaScript using standard HTML forms
3. **Client-side enhancement**: JavaScript adds validation, analytics, and better UX
4. **Graceful loading**: Shows appropriate loading states while initializing

## Examples

### Contact Form

```astro
---
import { VulForm } from '@vulform/astro';
---

<section class="py-16 bg-gray-50">
  <div class="max-w-2xl mx-auto px-4">
    <h2 class="text-3xl font-bold text-center mb-8">Get in Touch</h2>

    <VulForm
      templateId="contact-form"
      class="bg-white p-8 rounded-lg shadow-lg"
      prefill={{
        source: "Website Contact Form"
      }}
      enableAnalytics={true}
      spamProtection={true}
    />
  </div>
</section>
```

### Newsletter Signup

```astro
---
import { VulForm } from '@vulform/astro';
---

<div class="bg-blue-600 text-white py-8">
  <div class="max-w-4xl mx-auto px-4">
    <div class="text-center mb-6">
      <h3 class="text-2xl font-bold">Stay Updated</h3>
      <p class="text-blue-100">Get the latest news and updates</p>
    </div>

    <VulForm
      templateId="newsletter-signup"
      class="max-w-md mx-auto"
      theme="dark"
      resetOnSuccess={true}
      showSuccessMessage={true}
    />
  </div>
</div>
```

## TypeScript Support

The package includes full TypeScript support:

```astro
---
import type { VulFormProps } from '@vulform/astro';
import { VulForm } from '@vulform/astro';

interface Props {
  templateId: string;
  title?: string;
}

const { templateId, title = "Contact Form" }: Props = Astro.props;

const formConfig: VulFormProps = {
  templateId,
  apiKey: process.env.VULFORM_API_KEY!,
  theme: 'auto',
  enableAnalytics: true,
  spamProtection: true,
};
---

<div>
  <h2>{title}</h2>
  <VulForm {...formConfig} />
</div>
```

## License

MIT © [VulForm](https://vulform.dev)