npm package: @octopuslabs/react-multi-step-form
Description: A highly customizable, type-safe React multi-step form builder with progress tracking, validation, and beautiful UI components
Author: Sebastian Breit
Latest version: 0.1.0

# React Multi-Step Form Builder

A highly customizable, type-safe React multi-step form library with progress tracking, validation, and beautiful UI components. Build complex onboarding flows, surveys, or registration processes with ease using JSON configuration.

[![npm version](https://img.shields.io/npm/v/@yourscope/react-multi-step-form.svg)](https://www.npmjs.com/package/@yourscope/react-multi-step-form)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## Features

- 🎨 **JSON-Powered** - Define your entire form structure in a simple JSON configuration
- ✨ **Smooth Transitions** - Fluid, animated transitions between form steps
- 📊 **Progress Tracking** - Visual progress bar shows users their position in the flow
- ✅ **Built-in Validation** - Support for required fields and custom regex validation
- 🎯 **Rich Form Elements** - Text, email, password, select, textarea, radio, and checkbox groups
- 🔄 **State Persistence** - Save and restore form progress
- 💪 **TypeScript** - Fully typed for better developer experience
- 🎭 **Customizable** - Themeable components with Tailwind CSS
- ♿ **Accessible** - Built with accessibility in mind

## Installation

```bash
# npm
npm install @yourscope/react-multi-step-form

# yarn
yarn add @yourscope/react-multi-step-form

# pnpm
pnpm add @yourscope/react-multi-step-form
```

**Note:** This library requires React 18+ and uses Tailwind CSS for styling.

## Quick Start

### 1. Basic Usage

```tsx
import React, { useState, useEffect } from 'react';
import { MultiStepForm, FormConfig, FormData } from '@yourscope/react-multi-step-form';

function App() {
  const [formConfig, setFormConfig] = useState<FormConfig | null>(null);

  useEffect(() => {
    // Load your form configuration
    fetch('/path/to/form-config.json')
      .then(res => res.json())
      .then(data => setFormConfig(data));
  }, []);

  const handleSubmit = (formData: FormData) => {
    console.log('Form submitted:', formData);
    // Send to your API, etc.
  };

  if (!formConfig) return <div>Loading...</div>;

  return (
    <div className="min-h-screen bg-gray-900 flex items-center justify-center p-4">
      <div className="w-full max-w-2xl">
        <MultiStepForm config={formConfig} onSubmit={handleSubmit} />
      </div>
    </div>
  );
}
```

### 2. Form Configuration Example

Create a JSON configuration file:

```json
{
  "formId": "user-onboarding",
  "title": "Welcome Onboarding",
  "welcome": {
    "title": "Welcome!",
    "message": "Let's get you set up in just a few steps.",
    "buttonText": "Get Started"
  },
  "steps": [
    {
      "id": "step1",
      "title": "Personal Information",
      "description": "Tell us about yourself",
      "fields": [
        {
          "id": "fullName",
          "label": "Full Name",
          "type": "text",
          "placeholder": "John Doe",
          "required": true
        },
        {
          "id": "email",
          "label": "Email Address",
          "type": "email",
          "placeholder": "john@example.com",
          "required": true,
          "validationRegex": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
          "validationMessage": "Please enter a valid email address"
        }
      ]
    },
    {
      "id": "step2",
      "title": "Preferences",
      "description": "Customize your experience",
      "fields": [
        {
          "id": "interests",
          "label": "What are you interested in?",
          "type": "checkbox-group",
          "required": true,
          "options": [
            { "value": "tech", "label": "Technology" },
            { "value": "design", "label": "Design" },
            { "value": "business", "label": "Business" }
          ],
          "allowOther": true
        }
      ]
    }
  ],
  "completion": {
    "title": "All Done!",
    "message": "Thank you for completing the form.",
    "buttonText": "Start Over"
  }
}
```

### 3. Save/Load Progress

```tsx
import React, { useRef } from 'react';
import { MultiStepForm, MultiStepFormHandle, FormConfig } from '@yourscope/react-multi-step-form';

function App() {
  const formRef = useRef<MultiStepFormHandle>(null);
  const formConfig: FormConfig = /* your config */;

  const saveProgress = () => {
    if (formRef.current) {
      const state = formRef.current.getState();
      localStorage.setItem('formProgress', JSON.stringify(state));
      alert('Progress saved!');
    }
  };

  const loadProgress = () => {
    const saved = localStorage.getItem('formProgress');
    if (saved && formRef.current) {
      formRef.current.restoreState(JSON.parse(saved));
      alert('Progress restored!');
    }
  };

  return (
    <>
      <MultiStepForm
        ref={formRef}
        config={formConfig}
        onSubmit={(data) => console.log(data)}
      />
      <button onClick={saveProgress}>Save</button>
      <button onClick={loadProgress}>Load</button>
    </>
  );
}
```

## API Reference

### Components

#### `<MultiStepForm />`

The main form component.

**Props:**
- `config: FormConfig` - The form configuration object (required)
- `onSubmit?: (formData: FormData) => void` - Callback when form is submitted

**Ref Methods (via `MultiStepFormHandle`):**
- `getState(): FormState` - Get current form state
- `restoreState(state: FormState): void` - Restore saved state

### Types

```typescript
interface FormConfig {
  formId: string;
  title: string;
  welcome?: WelcomeConfig;
  steps: FormStep[];
  completion?: CompletionConfig;
}

interface FormStep {
  id: string;
  title: string;
  description?: string;
  fields: FormField[];
}

interface FormField {
  id: string;
  label: string;
  type: FormFieldType;
  placeholder?: string;
  required?: boolean;
  validationRegex?: string;
  validationMessage?: string;
  options?: Array<{ value: string; label: string }>;
  allowOther?: boolean;
}

type FormFieldType =
  | 'text'
  | 'email'
  | 'password'
  | 'tel'
  | 'number'
  | 'textarea'
  | 'select'
  | 'radio-group'
  | 'checkbox-group';

type FormData = Record<string, string>;
```

## Field Types

| Type | Description |
|------|-------------|
| `text` | Single-line text input |
| `email` | Email input with validation |
| `password` | Password input (masked) |
| `tel` | Telephone number input |
| `number` | Numeric input |
| `textarea` | Multi-line text input |
| `select` | Dropdown selection |
| `radio-group` | Single choice from options |
| `checkbox-group` | Multiple choice from options |

All `radio-group` and `checkbox-group` fields support `allowOther: true` to add an "Other" option with a text input.

## Styling

This library uses Tailwind CSS. Make sure Tailwind is configured in your project:

```bash
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init
```

Update your `tailwind.config.js`:

```js
module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
    "./node_modules/@yourscope/react-multi-step-form/dist/**/*.js"
  ],
  // ... rest of config
}
```

## Examples

Check out the [examples](./examples) directory for a full working demo.

To run the demo locally:

```bash
git clone https://github.com/octopuslabs-fl/Generic-Form-Builder.git
cd Generic-Form-Builder
npm install
npm run dev
```

## Development

### Building the Library

```bash
# Build for production
npm run build:lib

# This generates:
# - dist/index.mjs (ES module)
# - dist/index.cjs (CommonJS)
# - dist/index.d.ts (TypeScript types)
```

### Running the Demo

```bash
npm run dev
```

## Contributing

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

## License

MIT © [Your Name]

## Support

- 🐛 [Report issues](https://github.com/yourusername/Generic-Form-Builder/issues)
- 💬 [Discussions](https://github.com/yourusername/Generic-Form-Builder/discussions)
- 📖 [Documentation](https://github.com/yourusername/Generic-Form-Builder#readme)

---

**Note:** Before publishing to npm, remember to:
1. Update package name in `package.json` (remove `@yourscope/` or use your actual scope)
2. Add your author information
3. Update repository URLs
4. Add a LICENSE file
5. Test the build with `npm run build:lib`