🦀 BertUI Forms - Heavily Packed React Forms for BertUI

<div align="center">
  <h1>⚡ BertUI Forms v0.0.1-beta.1</h1>
  <p><strong>Heavily packed forms for BertUI - Validation, persistence, file uploads, wizards, and more!</strong></p>
  <p>Zero config. Just works. 🚀</p>
</div>

<div align="center">
  <img src="https://img.shields.io/badge/version-0.0.1--beta.1-blue" alt="version" />
  <img src="https://img.shields.io/badge/build-bun-f472b6" alt="bun" />
  <img src="https://img.shields.io/badge/react-18.2.0-61dafb" alt="react" />
  <img src="https://img.shields.io/badge/elysia-optional-purple" alt="elysia" />
  <img src="https://img.shields.io/badge/license-MIT-green" alt="license" />
</div>

---

## 📦 Installation

```bash
# In your BertUI project
bun add bertui-forms@beta

✨ Features

| Feature | Description | Status | |---------|-------------|--------| | ✅ Form Core | Form state management, validation, submission | ✅ | | ✅ Input Types | Text, email, password, number, etc. | ✅ | | ✅ Textarea | Multi-line with character counter | ✅ | | ✅ Select | Dropdown with search, multiple selection | ✅ | | ✅ Checkbox | Single checkbox with label | ✅ | | ✅ RadioGroup | Radio button groups | ✅ | | ✅ FileUpload | Drag & drop, preview, validation | ✅ | | ✅ Wizard | Multi-step forms with progress | ✅ | | ✅ Validation | String shorthand, functions, schemas | ✅ | | ✅ Persistence | localStorage, sessionStorage, auto-save | ✅ | | ✅ Drafts | Save/load form drafts | ✅ | | ✅ Server Actions | Elysia integration (optional) | ✅ | | ✅ TypeScript | Full type support | ✅ | | 🚀 Optimistic Updates | Coming soon | ⏳ | | 🚀 Field Arrays | Dynamic fields | ⏳ |

🚀 Quick Start

import { Form, Input, Button } from 'bertui-forms';
import 'bertui-forms/dist/bertui-forms.css';

function LoginForm() {
  const handleSubmit = (values) => {
    console.log('Login:', values);
  };

  return (
    <Form onSubmit={handleSubmit}>
      <Input name="email" type="email" label="Email" required />
      <Input name="password" type="password" label="Password" required />
      <Button type="submit">Log In</Button>
    </Form>
  );
}

📚 Complete Examples

1. Basic Form

<Form onSubmit={handleSubmit}>
  <Input name="name" label="Name" required />
  <Input name="email" type="email" label="Email" required />
  <Button>Submit</Button>
</Form>

2. Validation (Multiple Ways)

String shorthand:

<Input name="email" validate="required|email" />
<Input name="password" validate="required|minLength:8" />

Array of validators:

<Input 
  name="username" 
  validate={[
    validators.required,
    validators.minLength(3),
    (v) => !v.includes(' ') || 'No spaces allowed'
  ]}
/>

Object schema:

const validate = createValidator({
  email: 'required|email',
  age: [validators.required, validators.min(18)],
  website: (v) => {
    if (v && !v.startsWith('https://')) {
      return 'Must use HTTPS';
    }
  }
});

<Form validate={validate}>
  {/* fields */}
</Form>

3. Select with Search

<Select
  name="country"
  label="Country"
  options={[
    { value: 'us', label: '🇺🇸 United States' },
    { value: 'ca', label: '🇨🇦 Canada' },
    { value: 'uk', label: '🇬🇧 United Kingdom' }
  ]}
  searchable
  required
/>

4. File Upload with Preview

<FileUpload
  name="avatar"
  label="Profile Picture"
  accept="image/*"
  maxSize={2} // 2MB
  preview
  dragAndDrop
  required
/>

5. Multi-step Wizard

<Form onSubmit={handleSubmit}>
  <Wizard>
    <Step title="Personal Info">
      <Input name="name" required />
      <Input name="email" required />
    </Step>
    
    <Step title="Account">
      <Input name="password" type="password" required />
    </Step>
    
    <Step title="Review">
      <p>Review your information</p>
    </Step>
  </Wizard>
</Form>

6. Auto-save & Persistence

// Automatic persistence
<Form persist="local" persistKey="contact-form">
  <Input name="title" />
  <Textarea name="content" />
  <Button>Save</Button>
</Form>

// Manual draft management
const draftManager = new FormDraftManager('blog-post');

// Save draft
draftManager.saveDraft(form.values);

// Load draft
const draft = draftManager.loadDraft();

// Check if draft exists
if (draftManager.hasDraft()) {
  // Show resume option
}

7. Custom Hooks

function CustomForm() {
  const form = useForm({
    initialValues: { counter: 0 },
    onSubmit: (values) => console.log(values)
  });

  return (
    <Form form={form}>
      <span>Count: {form.values.counter}</span>
      <Button onClick={() => form.setValue('counter', form.values.counter + 1)}>
        Increment
      </Button>
    </Form>
  );
}

8. Server Actions (with Elysia)

// Client component
<Form action="/api/contact" method="POST">
  <Input name="email" required />
  <Textarea name="message" required />
  <Button>Send</Button>
</Form>

// Server (Elysia)
import { createFormAction } from 'bertui-forms';

export const contactHandler = createFormAction(async (body) => {
  await sendEmail(body.email, body.message);
  return { success: true };
});

🎯 API Reference

<Form> Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | onSubmit | (values) => void | - | Submit handler | | action | string | - | Server endpoint URL | | method | string | 'POST' | HTTP method | | validate | object \| function | - | Validation rules | | validationMode | 'onChange' \| 'onBlur' \| 'onSubmit' | 'onSubmit' | When to validate | | initialValues | object | {} | Initial form values | | persist | 'local' \| 'session' | - | Enable persistence | | persistKey | string | - | Key for persistence | | onSuccess | (result) => void | - | Success callback | | onError | (error) => void | - | Error callback |

<Input> Props

| Prop | Type | Description | |------|------|-------------| | name | string | Field name (required) | | type | string | Input type (text, email, password, etc.) | | label | string | Field label | | required | boolean | Mark as required | | validate | string \| array \| function | Validation rules | | placeholder | string | Placeholder text |

<Select> Props

| Prop | Type | Description | |------|------|-------------| | options | array | { value, label } array | | searchable | boolean | Enable search | | multiple | boolean | Allow multiple selection |

<FileUpload> Props

| Prop | Type | Description | |------|------|-------------| | accept | string | Accepted file types | | maxSize | number | Max size in MB | | preview | boolean | Show image previews | | dragAndDrop | boolean | Enable drag & drop | | multiple | boolean | Allow multiple files |

useForm() Return Value

| Property | Type | Description | |----------|------|-------------| | values | object | Current form values | | errors | object | Validation errors | | touched | object | Fields that have been blurred | | isSubmitting | boolean | Form is submitting | | isSuccess | boolean | Form submitted successfully | | serverError | string | Server error message | | handleChange | function | Change handler | | handleBlur | function | Blur handler | | handleSubmit | function | Submit handler | | reset | function | Reset form | | setValue | function | Set field value |

🛠️ Storage API

import { 
  saveToStorage, 
  loadFromStorage, 
  FormDraftManager,
  StorageTypes 
} from 'bertui-forms';

// Save data
saveToStorage(StorageTypes.LOCAL, 'my-key', data);

// Load data
const data = loadFromStorage(StorageTypes.LOCAL, 'my-key');

// Draft manager
const drafts = new FormDraftManager('form-id');
drafts.saveDraft(values);
drafts.loadDraft();
drafts.hasDraft();
drafts.clearDraft();

// Storage info
const info = getStorageInfo(StorageTypes.LOCAL);
console.log(`Using ${(info.usage / 1024).toFixed(2)}KB`);

🎨 Styling

Import the CSS:

import 'bertui-forms/dist/bertui-forms.css';

Customize with CSS variables:

:root {
  --bertui-primary-color: #4299e1;
  --bertui-error-color: #e53e3e;
  --bertui-success-color: #48bb78;
  --bertui-border-radius: 0.375rem;
  --bertui-spacing: 1rem;
}

Or override classes:

.bertui-input {
  /* Your custom styles */
}
.bertui-button-primary {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

📦 Bundle Size

| Package | Size | |---------|------| | Core | ~42KB gzipped | | with all components | ~58KB gzipped | | with Elysia integration | +5KB (optional) |

🧪 Examples

Check out the showcase page for 13+ real-world examples:

1. Simple Form
2. Validation Showcase
3. Advanced Inputs
4. File Upload
5. Persistence & Auto-save
6. Multi-step Wizard
7. Custom Hooks
8. Server Actions
9. Dynamic Fields
10. Theming
11. Error Handling
12. Performance (50 fields)
13. Complete Checkout

🤝 Contributing

git clone https://github.com/BunElysiaReact/bertui-forms
cd bertui-forms
bun install
bun run build

📄 License

MIT © Ernest