zunokit-builder/README.md

🎨 Figma-style drag-and-drop UI builder for React developers. Create UI visually, export clean Tailwind CSS code. Perfect for rapid prototyping and component creation.

# zunokit-builder

🎨 A React library for developers that enables **Figma-style drag-and-drop UI creation** with **clean, production-ready code generation**.

Built for developers who want to create UI quickly through visual editing, then export **hand-written quality code** that can be edited and deployed normally.

## ✨ Features

- 🎨 **Figma-style visual editor** - Intuitive drag & drop interface for developers
- ⚡ **Real-time code generation** - Automatically generates clean JSX components as you build
- 🧹 **Clean, maintainable output** - Produces hand-written quality code with proper component structure
- 🎯 **Development-only** - Builder interface only appears in `NODE_ENV=development`
- 🎨 **Tailwind-first** - Generated code uses Tailwind CSS classes exclusively (no inline styles)
- 📦 **Smart component modularization** - Automatically splits complex UI into reusable components
- 🔧 **Auto-imports** - Manages component imports automatically
- 🔄 **Layout persistence** - Saves layouts to `.zuno/layout.json` for versioning and undo
- 🎛️ **Property editing** - Visual property panel for editing component props
- 📱 **Responsive design** - Support for different viewport sizes and breakpoints

## 📦 Installation

```bash
npm install zunokit-builder
# or
yarn add zunokit-builder
# or
pnpm add zunokit-builder
```

**Peer Dependencies:**
- React >=16.8.0
- React DOM >=16.8.0

## 🚀 Quick Start

### 1. Wrap your app with ZunoBuilder

```jsx
import { ZunoBuilder } from 'zunokit-builder'

function App() {
  return (
    <ZunoBuilder>
      <div className="min-h-screen bg-gray-50">
        {/* Your existing app content */}
        <h1>My App</h1>
      </div>
    </ZunoBuilder>
  )
}

export default App
```

### 2. Start development

```bash
npm run dev
```

### 3. Open the builder

In development mode, you'll see an "Open Builder" button in the top-right corner. Click it to open the visual editor.

### 4. Build your UI

- 📝 Drag components from the sidebar (Text, Button, Input, etc.)
- 🎯 Click elements to select and edit their properties
- 📐 Resize and position elements visually
- 💾 Changes are automatically saved to `.zuno/layout.json`

## 🎛️ Configuration

```jsx
import { ZunoBuilder } from 'zunokit-builder'

function App() {
  return (
    <ZunoBuilder 
      config={{
        enabled: true, // Force enable (default: NODE_ENV === 'development')
        targetPath: './src/components/GeneratedUI.tsx',
        layoutPath: './.zuno/layout.json',
        theme: {
          primaryColor: '#3b82f6',
          borderRadius: '0.5rem'
        },
        ui: {
          position: 'top-right',
          showGrid: true,
          gridSize: 10
        },
        codegen: {
          componentNaming: 'PascalCase',
          generateTypes: true,
          includeComments: true
        }
      }}
    >
      <YourApp />
    </ZunoBuilder>
  )
}
```

## 🧩 Available Blocks

| Block | Description | Properties |
|-------|-------------|------------|
| **Text** | Typography elements | content, tag (h1-h6, p, span), fontSize, fontWeight, textAlign |
| **Button** | Interactive buttons | text, variant (default, destructive, outline, etc.), size, href |
| **Input** | Form inputs | type, placeholder, label, validation, size, variant |
| **Image** | Responsive images | src, alt, objectFit, loading, quality, rounded |
| **Section** | Layout containers | padding, margin, background, flexDirection, gap |
| **Card** | Card containers | background, border, borderRadius, shadow |

## 🔧 Advanced Usage

### Custom Configuration

```typescript
interface ZunoBuilderConfig {
  enabled?: boolean
  targetPath?: string
  layoutPath?: string
  theme?: {
    primaryColor?: string
    borderRadius?: string
    fontFamily?: string
  }
  ui?: {
    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
    showGrid?: boolean
    gridSize?: number
    darkMode?: boolean
  }
  codegen?: {
    componentNaming?: 'PascalCase' | 'camelCase' | 'kebab-case'
    fileOrganization?: 'single-file' | 'component-per-file' | 'grouped-by-type'
    generateTypes?: boolean
    includeComments?: boolean
  }
}
```

### Using with Next.js

```jsx
// pages/_app.js or app/layout.js
import { ZunoBuilder } from 'zunokit-builder'

function MyApp({ Component, pageProps }) {
  return (
    <ZunoBuilder>
      <Component {...pageProps} />
    </ZunoBuilder>
  )
}

export default MyApp
```

### TypeScript Support

Full TypeScript support with comprehensive type definitions:

```typescript
import { ZunoBuilder, ZunoBuilderConfig, ZunoBlock } from 'zunokit-builder'

const config: ZunoBuilderConfig = {
  enabled: process.env.NODE_ENV === 'development',
  targetPath: './src/components/Generated.tsx'
}
```

## 🏗️ How It Works

1. **Development Mode**: Builder appears only when `NODE_ENV=development`
2. **Visual Editing**: Drag, drop, and configure UI elements visually
3. **Real-time Generation**: Every change generates clean JSX code
4. **Clean Output**: Generated code looks like hand-written components
5. **Production Ready**: Builder disappears in production builds

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🔗 Links

- [GitHub Repository](https://github.com/zunokit/builder)
- [Documentation](https://zunokit.github.io/builder)
- [Issue Tracker](https://github.com/zunokit/builder/issues)
- [Changelog](CHANGELOG.md)

---

**Made with ❤️ by the Zuno Team**