npm package: @productcolab/zodiac
Description: A powerful React library for building dynamic, schema-driven forms with visual rule building capabilities. Generate forms from Zod schemas, create conditional logic visually, and build adaptive user experiences.
Author: ProductColab
Latest version: 0.1.0

# zodiac

Dynamic schema-driven forms for React with visual rule building.

[![npm version](https://img.shields.io/npm/v/zodiac.svg)](https://www.npmjs.com/package/zodiac)
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)

## Features

- **Schema-driven**: Generate forms from Zod schemas
- **Visual rule builder**: Create conditional logic without code
- **Type-safe**: Full TypeScript support with validation
- **Rich field types**: 20+ built-in field components
- **CLI tools**: Project scaffolding and code generation

## Quick Start

```bash
npm install zodiac
```

### Simple Form

```tsx
import { zodiac, field } from "zodiac";

const userForm = zodiac.form({
  name: field.text({ placeholder: "Full name" }),
  email: field.email(),
  age: field.slider({ min: 18, max: 100 }),
  category: field.select(["personal", "business"]),
});

function App() {
  return userForm.render({
    onSubmit: (data) => console.log(data),
    columns: 2,
  });
}
```

### With Zod Schema

```tsx
import { z } from "zod";
import { SchemaForm } from "zodiac";

const schema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
  age: z.number().min(18),
});

function App() {
  return <SchemaForm schema={schema} onSubmit={(data) => console.log(data)} />;
}
```

## Architecture

```mermaid
graph LR
  A[Zod Schema] --> B[JSON Schema]
  A --> C[Field Registry]
  B --> D[Form Renderer]
  C --> D
  E[Rule Builder] --> F[Conditional Logic]
  F --> D
  D --> G[React Form]
```

zodiac uses Zod v4's JSON Schema conversion and registry system to separate form structure from UI metadata, enabling clean schemas with rich form capabilities.

## Field Types

```tsx
const form = zodiac.form({
  // Text inputs
  email: field.email(),
  password: field.password(),
  url: field.url(),
  phone: field.phone(),

  // Numbers
  rating: field.rating(5),
  price: field.slider({ min: 0, max: 1000 }),
  quantity: field.number({ min: 1, max: 100 }),

  // Rich content
  bio: field.textarea({ rows: 4 }),
  content: field.richText(),
  signature: field.signature(),

  // File uploads
  avatar: field.image(),
  documents: field.file({ multiple: true }),

  // Complex fields
  address: field.address(),
  dateRange: field.dateRange(),
  tags: field.array(field.text()),
});
```

## Conditional Logic

### Visual Rule Builder

```tsx
import { RuleBuilder } from "zodiac";

const fields = {
  accountType: { type: "string", options: ["personal", "business"] },
  companyName: { type: "string" },
};

<RuleBuilder fields={fields} onRulesChange={setRules} />;
```

### Programmatic Rules

```tsx
const rules = [
  {
    condition: { field: "accountType", operator: "equals", value: "business" },
    action: { type: "field-visibility", field: "companyName", visible: true },
  },
];

<RuleBasedSchemaForm schema={schema} rules={rules} />;
```

## CLI Tools

```bash
# Install CLI
npm install -g zodiac

# Create new project
zodiac init my-app --template nextjs

# Generate components
zodiac generate contact-form

# Generate documentation
zodiac docs --watch --open

# Validate schemas
zodiac validate src/
```

## API Reference

### zodiac.form(fields)

Creates a form with the streamlined API.

```tsx
const form = zodiac.form({
  name: field.text(),
  email: field.email(),
});
```

### SchemaForm

Renders forms from Zod schemas.

| Prop       | Type                           | Description             |
| ---------- | ------------------------------ | ----------------------- |
| `schema`   | `ZodObject`                    | Zod schema definition   |
| `onSubmit` | `function`                     | Form submission handler |
| `columns`  | `1 \| 2 \| 3`                  | Layout columns          |
| `spacing`  | `compact \| normal \| relaxed` | Field spacing           |

### RuleBuilder

Visual interface for creating conditional logic.

| Prop            | Type           | Description         |
| --------------- | -------------- | ------------------- |
| `fields`        | `FieldSchemas` | Available fields    |
| `onRulesChange` | `function`     | Rule change handler |
| `initialRules`  | `Rule[]`       | Starting rules      |

## Examples

- [Basic Form](./examples/basic-form)
- [Conditional Logic](./examples/conditional-logic)
- [File Uploads](./examples/file-uploads)
- [Multi-step Forms](./examples/multi-step)

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.

## License

MIT