formcn 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Fares Galal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,294 @@
+# formcn
+
+[![npm version](https://img.shields.io/npm/v/formcn.svg)](https://www.npmjs.com/package/formcn)
+[![npm downloads](https://img.shields.io/npm/dw/formcn.svg)](https://www.npmjs.com/package/formcn)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+> Schema-driven React form generator built on top of React Hook Form, Zod, and shadcn/ui.
+
+formcn generates fully typed, validated React form components from an interactive CLI workflow.
+It is designed to reduce boilerplate while staying aligned with shadcn/ui conventions.
+
+---
+
+## Features
+
+- Zero-configuration form generation
+- Type-safe schemas using Zod
+- shadcn/ui component integration
+- Single-step and multi-step forms
+- Schema-first validation
+- Interactive CLI workflow
+- Automatic dependency detection and installation
+- Predefined templates for common use cases
+
+---
+
+## Prerequisites
+
+Before using formcn, ensure you have:
+
+- Node.js 18+
+- A React project with TypeScript
+- shadcn/ui initialized in your project
+
+Initialize shadcn/ui if needed:
+
+```bash
+npx shadcn@latest init
+```
+
+---
+
+## Installation
+
+Install globally using npm:
+
+```bash
+npm install -g formcn
+```
+
+Or using yarn:
+
+```bash
+yarn global add formcn
+```
+
+Or run directly with npx:
+
+```bash
+npx formcn
+```
+
+---
+
+## Usage
+
+Run the CLI:
+
+```bash
+formcn
+```
+
+The interactive workflow will guide you through:
+
+1. Form name
+2. Form type (single-step or multi-step)
+3. Template selection
+4. Field definitions and validation rules
+5. Style preset selection
+
+### Example
+
+```bash
+$ formcn
+
+formcn
+
+✔ react-hook-form detected
+✔ @hookform/resolvers detected
+✔ zod detected
+✔ shadcn/ui components detected
+
+Form name: register
+Form type: single step
+Template: registration
+Preset: default
+
+✔ Form generated at src/components/forms/register
+```
+
+---
+
+## Generated Output
+
+### Single-step form
+
+```txt
+src/components/forms/{formName}/
+├── schema.ts
+└── form.tsx
+```
+
+### Multi-step form
+
+```txt
+src/components/forms/user-registration/
+├── personal-info-schema.ts
+├── personalInfoStep.tsx
+├── account-details-schema.ts
+├── accountDetailsStep.tsx
+├── contact-info-schema.ts
+├── contactInfoStep.tsx
+└── UserRegistrationForm.tsx
+```
+
+---
+
+## Supported Field Types
+
+- Text
+- Email
+- Password (with optional confirmation)
+- Number
+- URL
+- Textarea
+- Select
+- Checkbox
+- Radio
+- Date
+
+---
+
+## Templates
+
+### Single-step
+
+- Registration
+- Login
+- Contact
+
+### Multi-step
+
+- Registration (personal info, account details, contact info)
+
+---
+
+## Style Presets
+
+### Single-step
+
+- `default` — minimal layout with subtle borders and spacing
+
+### Multi-step
+
+- `minimal`
+- `sidebarStepper`
+- `softType`
+- `stepperTop`
+
+---
+
+## Example Output
+
+### Schema (`schema.ts`)
+
+```ts
+import { z } from "zod";
+
+export const schema = z
+  .object({
+    first_name: z.string().min(1, "First Name is required"),
+    last_name: z.string().min(1, "Last Name is required"),
+    email: z.string().email("Invalid email"),
+    password: z.string().min(8, "Password must be at least 8 characters"),
+    passwordConfirmation: z.string(),
+    age: z.coerce.number().min(18, "Age must be at least 18"),
+    website: z.string().url("Invalid URL").optional().or(z.literal("")),
+    bio: z.string().optional(),
+    country: z.union([z.literal("us"), z.literal("ca"), z.literal("uk")], {
+      error: "Please select a country",
+    }),
+    newsletter: z.boolean().optional(),
+  })
+  .refine((data) => data.password === data.passwordConfirmation, {
+    message: "Passwords do not match",
+    path: ["passwordConfirmation"],
+  });
+
+export type SchemaFormValues = z.infer<typeof schema>;
+```
+
+### Form (`form.tsx`)
+
+```tsx
+"use client";
+
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { Button } from "@/components/ui/button";
+import { FieldGroup } from "@/components/ui/field";
+import { schema, type SchemaFormValues } from "./schema";
+
+export default function RegisterForm() {
+  const form = useForm<SchemaFormValues>({
+    resolver: zodResolver(schema),
+  });
+
+  function onSubmit(values: SchemaFormValues) {
+    console.log(values);
+  }
+
+  return (
+    <form
+      onSubmit={form.handleSubmit(onSubmit)}
+      className="space-y-6 max-w-3xl mx-auto border rounded-lg p-6"
+    >
+      <FieldGroup />
+      <div className="flex justify-end">
+        <Button type="submit" disabled={!form.formState.isValid}>
+          Submit
+        </Button>
+      </div>
+    </form>
+  );
+}
+```
+
+---
+
+## Troubleshooting
+
+### Command not found
+
+Ensure your global npm bin directory is in your PATH:
+
+```bash
+npm config get prefix
+```
+
+### shadcn/ui not detected
+
+```bash
+npx shadcn@latest init
+```
+
+### Missing dependencies
+
+```bash
+npm install react-hook-form @hookform/resolvers zod
+```
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+1. Fork the repository
+2. Create a feature branch
+3. Commit your changes
+4. Push the branch
+5. Open a pull request
+
+---
+
+## License
+
+MIT License
+
+---
+
+## Author
+
+**Fares Galal**
+
+---
+
+## Acknowledgments
+
+- React Hook Form
+- Zod
+- shadcn/ui
+- Tailwind CSS
+- TypeScript

package/bin/index.js

@@ -0,0 +1,71 @@
+import { intro, outro, select } from "@clack/prompts";
+import {
+  askFormType,
+  askFields,
+  askFormName,
+  askSteps,
+  askFormTemplate,
+  askFormPreset,
+} from "../utils/prompts.js";
+import { generateSingleForm } from "../generators/form-generator.js";
+import { generateMultiForm } from "../generators/multi-form-generator.js";
+import {
+  singleFormPresets,
+  multiFormPresets,
+} from "../utils/tailwind-presets.js";
+import {
+  SINGLE_FIELD_TEMPLATES,
+  MULTI_STEP_TEMPLATES,
+} from "../utils/templates.js";
+import { ensurePackages } from "../utils/ensurePackages.js";
+
+intro("formcn");
+
+await ensurePackages();
+
+const formName = await askFormName();
+const formType = await askFormType();
+
+const formTemplateChoice = await askFormTemplate(formType);
+
+let presetKey;
+
+if (formTemplateChoice === "template") {
+  if (formType === "single") {
+    const templateKeys = Object.keys(SINGLE_FIELD_TEMPLATES);
+    const templateChoice = await select({
+      message: "Choose a template:",
+      options: templateKeys.map((key) => ({ value: key, label: key })),
+    });
+    presetKey = await askFormPreset(singleFormPresets);
+    await generateSingleForm({
+      formName,
+      fields: SINGLE_FIELD_TEMPLATES[templateChoice],
+      presetKey,
+    });
+  } else {
+    const templateKeys = Object.keys(MULTI_STEP_TEMPLATES);
+    const templateChoice = await select({
+      message: "Choose a template:",
+      options: templateKeys.map((key) => ({ value: key, label: key })),
+    });
+    presetKey = await askFormPreset(multiFormPresets);
+    await generateMultiForm({
+      formName,
+      steps: MULTI_STEP_TEMPLATES[templateChoice],
+      presetKey,
+    });
+  }
+} else {
+  if (formType === "single") {
+    const fields = await askFields();
+    presetKey = await askFormPreset(singleFormPresets);
+    await generateSingleForm({ formName, fields, presetKey });
+  } else {
+    presetKey = await askFormPreset(multiFormPresets);
+    const steps = await askSteps();
+    await generateMultiForm({ formName, steps, presetKey });
+  }
+}
+
+outro("✅ Form created successfully");

package/generators/form-generator.js

@@ -0,0 +1,152 @@
+import fs from "fs-extra";
+import path from "path";
+import { generateZodSchema } from "./schema-generator.js";
+import { toPascalCaseForm } from "../utils/lib.js";
+import {
+  generateImports,
+  getComponentUsage,
+  getDefaultValue,
+  renderError,
+  renderInputByType,
+} from "./form-ui-templates.js";
+import { singleFormPresets } from "../utils/tailwind-presets.js";
+import { confirm, isCancel } from "@clack/prompts";
+
+export async function generateSingleForm({ formName, fields, presetKey }) {
+  const baseDir = fs.existsSync(path.resolve("src"))
+    ? path.resolve("src/components/forms")
+    : path.resolve("components/forms");
+
+  const formDir = path.join(baseDir, formName);
+
+  const exists = await fs.pathExists(formDir);
+
+  if (exists) {
+    const overwrite = await confirm({
+      message: `Form "${formName}" already exists. Overwrite it?`,
+      initialValue: false,
+    });
+
+    if (isCancel(overwrite) || !overwrite) {
+      console.log("❌ Operation cancelled.");
+      process.exit(0);
+    }
+    await fs.remove(formDir);
+  }
+
+  try {
+    await fs.ensureDir(formDir);
+
+    const enhancedFields = addPasswordConfirmation(fields);
+
+    await fs.writeFile(
+      path.join(formDir, "schema.ts"),
+      generateZodSchema(enhancedFields)
+    );
+
+    await fs.writeFile(
+      path.join(formDir, "form.tsx"),
+      generateFormComponent(formName, enhancedFields, presetKey)
+    );
+
+    console.log(`✅ Form generated at ${formDir}`);
+  } catch (error) {
+    await fs.remove(formDir);
+    console.error("❌ Failed to generate form. Changes reverted.");
+    throw error;
+  }
+}
+
+function addPasswordConfirmation(fields) {
+  return fields.flatMap((field) =>
+    field.type === "password" && field.confirm
+      ? [
+          field,
+          {
+            ...field,
+            name: `${field.name}Confirmation`,
+            label: "Confirm Password",
+            isConfirmation: true,
+            confirmationFor: field.name,
+          },
+        ]
+      : field
+  );
+}
+
+function generateFormComponent(formName, fields, presetKey) {
+  const uses = getComponentUsage(fields);
+  const componentName = toPascalCaseForm(formName);
+  const preset = singleFormPresets[presetKey];
+  if (!preset) throw new Error(`Single form preset "${presetKey}" not found`);
+
+  const renderControllerContent = (f) => `
+    <FieldLabel htmlFor="${f.name}">${f.label}${
+    f.required ? ' <span className="text-red-500">*</span>' : ""
+  }
+</FieldLabel>
+    ${renderInputByType(f)}
+    ${renderError()}
+  `;
+
+  const renderFields = fields
+    .map((f) => {
+      const isCheckbox = f.type === "checkbox";
+
+      return `
+        <Controller
+          name="${f.name}"
+          control={form.control}
+          render={({ field, fieldState }) => (
+            ${
+              isCheckbox
+                ? `
+                  <>
+                    ${renderControllerContent(f, false)}
+                  </>
+                `
+                : `
+                  <Field data-invalid={fieldState.invalid}>
+                    ${renderControllerContent(f)}
+                  </Field>
+                `
+            }
+          )}
+        />
+      `;
+    })
+    .join("\n");
+
+  return `
+    "use client";
+    
+    ${generateImports(uses)}
+    import { schema, type SchemaFormValues } from "./schema";
+    
+    export default function ${componentName}() {
+      const form = useForm<SchemaFormValues>({
+        resolver: zodResolver(schema),
+        defaultValues: {
+          ${fields.map(getDefaultValue).join(",\n      ")}
+        },
+      });
+    
+      function onSubmit(data: SchemaFormValues) {
+        console.log(data);
+      }
+     
+      return (
+        <form onSubmit={form.handleSubmit(onSubmit)} className="${preset.form}">
+          <FieldGroup>
+            ${renderFields}
+          </FieldGroup>
+          <div className="${preset.buttonsWrapper}">
+            <Button type="submit" disabled={!form.formState.isValid}>
+              Submit
+            </Button>
+          </div>
+        </form>
+      );
+    }
+    `.trim();
+}

package/generators/form-ui-templates.js

@@ -0,0 +1,183 @@
+export const INPUT_TEMPLATES = {
+  textarea: (f) => `<Textarea
+      {...field}
+      id="${f.name}"
+      rows={4}
+      ${f.required ? "required" : ""}
+      aria-invalid={fieldState.invalid}
+    />`,
+
+  select: (
+    f
+  ) => `<Select value={field.value ?? ""} onValueChange={field.onChange}>
+    <SelectTrigger id="${f.name}" aria-invalid={fieldState.invalid}>
+      <SelectValue placeholder="Select ${f.label}" />
+    </SelectTrigger>
+    <SelectContent>
+      ${f.options
+        .map(
+          (opt) => `<SelectItem value="${opt.value}">${opt.label}</SelectItem>`
+        )
+        .join("\n    ")}
+    </SelectContent>
+  </Select>`,
+
+  checkbox: (f) => `<FieldGroup data-slot="checkbox-group">
+  <Field orientation="horizontal">
+    <Checkbox
+      id="${f.name}"
+      name={field.name}
+      checked={field.value}
+      onCheckedChange={field.onChange}
+      ${f.required ? "required" : ""}
+    />
+    <FieldLabel htmlFor="${f.name}" className="font-normal">
+      ${f.label}
+    </FieldLabel>
+  </Field>
+  </FieldGroup>`,
+
+  radio: (
+    f
+  ) => `<RadioGroup  value={field.value ?? ""} onValueChange={(val) => field.onChange(val === "" ? undefined : val)}>
+    ${f.options
+      .map(
+        (opt) => `<Field orientation="horizontal">
+      <RadioGroupItem value="${opt.value}" id="${f.name}-${opt.value}" />
+      <FieldLabel htmlFor="${f.name}-${opt.value}">${opt.label}</FieldLabel>
+    </Field>`
+      )
+      .join("\n  ")}
+  </RadioGroup>`,
+
+  number: (f) => `<Input
+    id="${f.name}"
+    type="number"
+    autoComplete="${f.autocomplete ?? "off"}"
+    ${f.required ? "required" : ""}
+    aria-invalid={fieldState.invalid}
+    value={field.value ?? ""}
+    onChange={(e) => field.onChange(e.target.value === "" ? undefined : Number(e.target.value))}
+    onBlur={field.onBlur}
+    ref={field.ref}
+  />`,
+
+  default: (f) => {
+    const type = ["text", "email", "password", "date"].includes(f.type)
+      ? f.type
+      : "text";
+    const defaultAutoComplete = {
+      text: "off",
+      email: "email",
+      password: "new-password",
+      date: "bday",
+    }[type];
+    return `<Input
+          {...field}
+          id="${f.name}"
+          type="${type}"
+          autoComplete="${f.autocomplete ?? defaultAutoComplete}"
+          ${f.required ? "required" : ""}
+          aria-invalid={fieldState.invalid}
+      />`;
+  },
+};
+
+export const COMPONENT_USAGE_MAP = {
+  textarea: { Textarea: true },
+  select: {
+    Select: true,
+    SelectTrigger: true,
+    SelectValue: true,
+    SelectContent: true,
+    SelectItem: true,
+  },
+  checkbox: { Checkbox: true },
+  radio: { RadioGroup: true, RadioGroupItem: true },
+  default: { Input: true },
+};
+
+export function renderInputByType(f) {
+  return INPUT_TEMPLATES[f.type]?.(f) || INPUT_TEMPLATES.default(f);
+}
+
+export function getComponentUsage(fields) {
+  const usage = {};
+
+  fields.forEach((f) => {
+    const components =
+      COMPONENT_USAGE_MAP[f.type] || COMPONENT_USAGE_MAP.default;
+    Object.assign(usage, components);
+  });
+
+  return usage;
+}
+
+export function generateImports(uses = {}, mode = "single") {
+  const importSet = new Set();
+
+  const componentImports = {
+    Input: `import { Input } from "@/components/ui/input";`,
+    Textarea: `import { Textarea } from "@/components/ui/textarea";`, // <--- add this
+    Select: `import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from "@/components/ui/select";`,
+    Checkbox: `import { Checkbox } from "@/components/ui/checkbox";`,
+    RadioGroup: `import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";`,
+  };
+
+  if (mode === "single") {
+    importSet.add(`import { useForm, Controller } from "react-hook-form";`);
+    importSet.add(`import { Button } from "@/components/ui/button";`);
+    importSet.add(`import { zodResolver } from "@hookform/resolvers/zod";`);
+    importSet.add(
+      `import { Field, FieldLabel, FieldError, FieldGroup } from "@/components/ui/field";`
+    );
+
+    Object.entries(uses).forEach(([component, used]) => {
+      if (used && componentImports[component])
+        importSet.add(componentImports[component]);
+    });
+  }
+
+  if (mode === "step") {
+    importSet.add(
+      `import { Controller, useFormContext } from "react-hook-form";`
+    );
+    importSet.add(
+      `import { Field, FieldLabel, FieldError, FieldGroup } from "@/components/ui/field";`
+    );
+
+    Object.entries(uses).forEach(([component, used]) => {
+      if (used && componentImports[component])
+        importSet.add(componentImports[component]);
+    });
+  }
+
+  if (mode === "multi") {
+    importSet.add(`import { useForm, FormProvider } from "react-hook-form";`);
+    importSet.add(`import { Button } from "@/components/ui/button";`);
+    importSet.add(`import { zodResolver } from "@hookform/resolvers/zod";`);
+  }
+
+  return Array.from(importSet).join("\n");
+}
+
+export function getDefaultValue(field) {
+  if (field.type === "checkbox") return `${field.name}: false`;
+  if (
+    field.type === "number" ||
+    field.type === "select" ||
+    field.type === "radio"
+  )
+    return `${field.name}: undefined`;
+  return `${field.name}: ""`;
+}
+
+export function renderError() {
+  return `
+  {fieldState.invalid && (
+    <FieldError className="text-left">
+      {fieldState.error?.message}
+    </FieldError>
+  )}
+  `;
+}