# Cloudwick Form Builder

Form Builder for Cloudwick

Version - 1.0.9

## Installation

### Option 1: CLI Installation (Recommended)

Install individual components using our CLI tool, similar to shadcn/ui:

```sh
# Initialize in your project
npx @cloudwick-formick/cli init

# Add specific components
npx @cloudwick-formick/cli add form-builder
npx @cloudwick-formick/cli add form-previewer

# Or use the short alias
npx cloudwick-ui add form-builder
```

### Option 2: Package Installation

Install the entire package in your project directory with:

```sh
# With npm:
npm i @cloudwick-formick/core

# With yarn:
yarn add @cloudwick-formick/core
```

## Requirements

This package has the following peer dependencies:
- React ^18.3.1
- React DOM ^18.3.1
- Node ^20.16.0
- Tailwind CSS ^3.4.13

## Available Components

Package provides the following components:

- **FormBuilder** - Complete form building interface with drag-and-drop
- **Form** - Preview and render forms
- **FormTheme** - Theme customization components
- **shared** - Shared utility components

## CLI Commands

### `init`
Initialize Cloudwick FormBuilder support files, Tailwind hooks, utilities, and config.

```bash
npx cloudwick-ui init
```

This command:
- Writes/updates `cloudwick-ui.json`
- Ensures `src/components`, `src/lib`, `src/constants`, `src/utils`, `src/hooks`, `src/mocks`, and `src/assets` exist
- Generates the `cn`, `generateId`, and `generateIdWithPrefix` helpers under `src/lib/utils.ts`
- Copies all supporting constants, hooks, theme helpers, and schema utilities from the registry
- Adds Astral UI CSS imports to your main entry file when present
- Attempts to inject alias configuration into `vite.config.(ts|js)` and `tsconfig.json`
- Installs core dependencies: `@cloudwick/astral-ui`, `@dnd-kit/*`, `use-immer`, `zod`, `tailwind-merge`, `clsx`, `react-signature-canvas`, and `libphonenumber-js`

| Option | Alias | Description |
|--------|-------|-------------|
| `--yes` | `-y` | Skip prompts and use defaults |
| `--cwd <dir>` | `-c` | Run initialization in another directory |

### `add`
Add one or more components (including FormBuilder) to your project.

```bash
npx cloudwick-ui add formbuilder
npx cloudwick-ui add formbuilder form-previewer form-theme
```

Behavior:
- Auto-runs `init` if `cloudwick-ui.json` is missing
- Resolves component dependencies (for example, `formbuilder` brings shared utilities and supporting UI wrappers)
- Copies files into the alias-backed `src/components` tree, preserving nested directories
- Transforms import paths to respect your alias preferences (`@formickComponents`, `@formickUtils`, etc.)
- Installs any external npm packages declared by the component
- Creates missing `index.ts` barrels and stub folders for FormBuilder internals

| Option | Alias | Description |
|--------|-------|-------------|
| `--yes` | `-y` | Bypass overwrite prompts |
| `--overwrite` | `-o` | Force-write files even if they exist |
| `--cwd <dir>` | `-c` | Target another working directory |
| `--path <path>` | `-p` | Place the component in a custom folder |

*Tip:* Running `npx cloudwick-ui add` without arguments opens an interactive multi-select list of available components.

### `list`
Display every component bundled with the registry, including FormBuilder and its companions.

```bash
npx cloudwick-ui list
```

Output includes the file count, npm dependencies, and internal dependencies so you know what will be installed before running `add`.

## Quick Start

```bash
# 1. Initialize (creates cloudwick-ui.json, aliases, utilities, and Tailwind glue)
npx cloudwick-ui init

# 2. Add FormBuilder and any related components
npx cloudwick-ui add formbuilder form-previewer form-theme

# 3. Confirm Astral UI CSS imports were injected
npx cloudwick-ui init --yes   # reruns setup, safe if you need to reapply styles

# 4. Start building
import FormBuilder from '@formickComponents/formbuilder/FormBuilder';
```

## Recommended Workflow

1. **Initialize once per repo** – runs scaffolding, ensures `src/constants`, `src/utils`, `src/hooks`, and Astral UI CSS imports exist.
2. **Review `cloudwick-ui.json`** – adjust Tailwind paths or alias targets if your layout differs.
3. **Add components** – `formbuilder`, `form-previewer`, `form-theme`, and `shared` helpers as needed.
4. **Wire aliases** – verify `tsconfig.json`/`vite.config.*` picked up the `@formick*` prefixes or add them manually.
5. **Import & customize** – hook the FormBuilder context to your data layer, extend field definitions, or align styles with your Tailwind token strategy.

## FormBuilder Component Overview

The FormBuilder component provides a comprehensive drag-and-drop form building experience with:

- **Drag-and-drop layouting** via `@dnd-kit/core` with contextual spacer logic for precise placement
- **Multi-page orchestration** with automatic page splitting, page-break layouts, and dynamic renumbering
- **Field, layout, header, and page inspectors** tied to the shared `formPagesContext`
- **Conditional logic** editors, modal UX, and validation builders powered by `zod` schemas
- **Theme management** through the embedded `FormTheme` component (colors, typography, spacing) plus live preview
- **Runtime rendering** by delegating to `@components/shared/FormRenderer`, ensuring parity between builder and embed experience
- **Notification hooks** using the Astral UI `Toast`

### Basic Usage

```tsx
import React from 'react';
import FormBuilder, { formPagesContext } from '@formickComponents/formbuilder/FormBuilder';
import { DEFAULT_FORM_CONFIG } from '@formickConstants';

export default function FormBuilderScreen() {
  return (
    <formPagesContext.Provider value={{ initialConfig: DEFAULT_FORM_CONFIG }}>
      <FormBuilder />
    </formPagesContext.Provider>
  );
}
```

### Previewing a Saved Form

```tsx
import FormRenderer from '@formickComponents/shared/FormRenderer';
import type { IFormConfig } from '@formickComponents/formbuilder/types';

export function LivePreview({ config }: { config: IFormConfig }) {
  return <FormRenderer formConfig={config} readOnly />;
}
```

## Documentation



## Import Paths

### Using CLI (Recommended)
When using the CLI, components are copied to your project and you import them locally:

```js
// After running: npx cloudwick-ui add form-builder
import { FormBuilder } from '@/components/ui/form-builder';
```

### Using Package Installation
You can import components from the main package:

```js
// Import from the main package
import { FormBuilder } from '@cloudwick-formick/core';
```

## Configuration (`cloudwick-ui.json`)

Created during `init` and located at the project root:

```json
{
  "style": "default",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "src/app/globals.css",
    "baseColor": "slate",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@formickComponents",
    "utils": "@formickUtils",
    "ui": "@formickComponents"
  }
}
```

You can tailor the Tailwind config path, CSS entry, color strategy, or alias names. Re-run `npx cloudwick-ui init --yes` anytime to regenerate supporting files without losing manual tweaks.

## Path Aliases & Utilities

`init` attempts to register the following aliases in both `tsconfig.json` and `vite.config.*` (if present):

- `@formickComponents` → `src/components`
- `@formickUtils` → `src/utils`
- `@formickConstants` → `src/constants`
- `@formickHooks`, `@formickAssets`, `@formickMocks`, and `@formickTypes`

If your framework uses a different config (e.g., Next.js app dir, CRA with `jsconfig.json`, Angular's `tsconfig.app.json`), replicate the mappings manually.

The generated `src/lib/utils.ts` exposes the `cn`, `generateId`, and `generateIdWithPrefix` helpers that the builder relies on—import them via `@formickUtils`.

## Styling & Tailwind Integration

- `init` injects Astral UI CSS imports into your main entry file so every copied component renders with the correct base styles and fonts
- Tailwind tokens (colors, spacing, typography) are referenced throughout the builder. Keep the generated CSS variables in your global stylesheet or map them to your design system
- `FormTheme` writes updates to the contextual theme object—use `useThemeStyles` to read/write theme overrides or persist them to your backend
- If you already have a tailor-made Tailwind setup, disable automatic CSS variables during `init` and wire the generated `CSS_DEFAULTS`, `STYLE_UTILS`, and color maps to your palette

## Troubleshooting

- **Path alias errors** – rerun `npx cloudwick-ui init --yes` or manually add the aliases to your bundler and TypeScript config. Confirm your IDE picks up `cloudwick-ui.json` for guidance
- **Missing styles or fonts** – ensure the Astral UI CSS imports live in your entry file and that Tailwind processes the generated CSS file. Remember to restart the dev server after `init`
- **Dependency conflicts** – the CLI installs the minimum versions required by FormBuilder. If your workspace already has newer versions, prefer letting your package manager dedupe; otherwise, pin them in `package.json`
- **Overwrite prompts** – pass `--yes --overwrite` to re-sync the component files when you pull new updates from the registry

## Why Use the CLI?

- **Own Your Code**: Components are copied to your project, so you can modify them
- **No Lock-in**: You're not dependent on our package versions
- **Better Performance**: No external dependencies in production
- **Customizable**: Modify components to fit your exact needs
- **Type Safety**: Full TypeScript support with your project's configuration