npm package: @generative-forms/react-form
Description: AI-powered React form components — render production-ready forms from JSON configuration
Latest version: 0.1.0

# @generative-forms/react-form

A robust React form engine based on generated JSON configurations and turns them into strictly typed multi-step form experiences.

## 1. Purpose

This package provides the UI layer for the Generative Forms ecosystem. It consumes a `FormConfiguration` (generated via AI or manual schema) and renders a fully functional form with:

- **Automatic Type Inference**: Deeply nested data structures are inferred directly from your config.
- **Multi-Step Orchestration**: Internal state management for navigation, validation, and data accumulation.
- **Context-Aware Validation**: Real-time validation powered by TanStack Form.

**Example Integrations:** See [gf-react-integrations](https://github.com/PWadeDev/gf-react-integrations) for example projects integrating this package with different React frameworks.

---

## 2. Requirements

- **React**: 18.0.0 or higher.

---

## 3. Setup

### 3.1 Style Setup

#### 3.1.1 Project without Tailwind

Import the desired bundled themed CSS file in your application's entry point:

```tsx
import "@generative-forms/react-form/themes/default.theme.css";
```

**Themes:**

You can import a specific theme instead of the default:

```tsx
import "@generative-forms/react-form/themes/blue.theme.css";
// or
import "@generative-forms/react-form/themes/green.theme.css";
// or
import "@generative-forms/react-form/themes/orange.theme.css";
// or
import "@generative-forms/react-form/themes/red.theme.css";
// or
import "@generative-forms/react-form/themes/violet.theme.css";
// or
import "@generative-forms/react-form/themes/yellow.theme.css";
```

**What's included:**

- Complete Tailwind v4 base styles and utilities
- shadcn/ui theme variables (light and dark mode)
- All component styles

#### 3.1.2 Project with Tailwind and Shadcn Theme

The library uses Tailwind utility classes with Tailwind and implemented shadcn theming. To ensure the required styles are bundled in your project, add the library's entry point to your CSS source scanning.

In your main CSS file (e.g., `globals.css`), include the `@source` directive pointing to the library's distribution:

```css
@import "tailwindcss";

/* Ensure Tailwind scans the library for required classes */
@source "<path>/<to>/node_modules/@generative-forms/react-form/dist/index.js";
```

**Theming Reference:**

- [shadcn/ui Themes](https://ui.shadcn.com/themes)
- [shadcn/ui Theme Customization](https://ui.shadcn.com/themes)

### 3.2 Dark Mode

Dark mode works via the `.dark` class on a parent element. Add the class to enable dark mode:

```tsx
<div className="dark">
  <GenerativeForm config={myForm} onSubmit={...} />
</div>
```

**Implementation options:**

- Manual toggle: Add/remove `.dark` class via JavaScript
- System preference: Use `prefers-color-scheme` media query
- Persistence: Store preference in localStorage

**Reference:**

- [Tailwind CSS Dark Mode](https://tailwindcss.com/docs/dark-mode)
- [shadcn/ui Dark Mode](https://ui.shadcn.com/docs/dark-mode)

## 4. Usage

### 4.1 Define Configuration

To get full IDE autocomplete and type safety, define your configuration using the `defineGenerativeFormConfig` helper.

> **Why?** This prevents TypeScript from "widening" your step and group keys to generic strings, allowing the engine to know exactly which fields exist at compile time.

```tsx
import { defineGenerativeFormConfig } from "@generative-forms/react-form";

const registrationForm = defineGenerativeFormConfig({
  id: "user-reg",
  ...
})
```

### 4.2 Implementation

The `GenerativeForm` component handles the rendering and state transitions.

```tsx
import { GenerativeForm } from "@generative-forms/react-form";

export function MyForm() {
  return (
    <GenerativeForm
      config={registrationForm}
      onStepSuccess={{
        personalStep: (data) => {
          console.log("Step saved:", data.nameGroup.firstName);
        },
      }}
      onSubmit={(allData) => {
        console.log("Form Complete:", allData.personalStep.nameGroup.firstName);
      }}
    />
  );
}
```