@classytic/formkit 1.0.1 → 1.0.3

package/README.md

@@ -1,273 +1,434 @@
-# @classytic/formkit
-
-A headless, type-safe form generation engine for React 18+ and React 19. Build dynamic forms from schemas with full TypeScript support and zero UI opinions.
-
-[![npm version](https://img.shields.io/npm/v/@classytic/formkit.svg)](https://www.npmjs.com/package/@classytic/formkit)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-## ✨ Features
-
-- 🎯 **Headless & UI-Agnostic**: Bring your own components (Shadcn, Material UI, Ant Design, or custom)
-- 📝 **Schema-Driven**: Generate complex forms from simple JSON schemas
-- 🔒 **Type-Safe**: Built with TypeScript, full type inference and autocomplete
-- ⚡ **Performance**: Optimized rendering with React 18/19 concurrent features
-- 🎨 **Variants**: Support multiple component styles (compact, default, custom)
-- 🔀 **Conditional Fields**: Show/hide fields based on form values
-- 🧩 **Composable**: Modular architecture with pluggable components
-- 🪝 **React Hook Form**: Built on top of the industry-standard form library
-- 🌲 **Tree-Shakeable**: Only bundle what you use
-
-## 📦 Installation
-
-```bash
-npm install @classytic/formkit react-hook-form
-# or
-yarn add @classytic/formkit react-hook-form
-# or
-pnpm add @classytic/formkit react-hook-form
-```
-
-## 🚀 Quick Start
-
-### 1. Create a Component Adapter
-
-Map your UI components to form field types:
-
-```tsx
-// form-adapter.tsx
-import { FormSystemProvider } from "@classytic/formkit";
-import { Input } from "@/components/ui/input";
-import { Select } from "@/components/ui/select";
-import { Checkbox } from "@/components/ui/checkbox";
-
-const components = {
-  text: Input,
-  email: Input,
-  select: Select,
-  checkbox: Checkbox,
-  // Add more field types as needed
-};
-
-const layouts = {
-  grid: ({ children, cols = 1 }) => (
-    <div className={`grid grid-cols-${cols} gap-4`}>{children}</div>
-  ),
-  section: ({ title, description, children }) => (
-    <div className="space-y-4">
-      {title && <h3 className="text-lg font-semibold">{title}</h3>}
-      {description && <p className="text-sm text-muted-foreground">{description}</p>}
-      {children}
-    </div>
-  ),
-};
-
-export function FormProvider({ children }: { children: React.ReactNode }) {
-  return (
-    <FormSystemProvider components={components} layouts={layouts}>
-      {children}
-    </FormSystemProvider>
-  );
-}
-```
-
-### 2. Define Your Schema
-
-```tsx
-import type { FormSchema } from "@classytic/formkit";
-
-const userFormSchema: FormSchema = {
-  sections: [
-    {
-      title: "Personal Information",
-      cols: 2,
-      fields: [
-        {
-          name: "firstName",
-          type: "text",
-          label: "First Name",
-          required: true,
-        },
-        {
-          name: "lastName",
-          type: "text",
-          label: "Last Name",
-          required: true,
-        },
-        {
-          name: "email",
-          type: "email",
-          label: "Email",
-          fullWidth: true,
-        },
-      ],
-    },
-    {
-      title: "Account Settings",
-      fields: [
-        {
-          name: "role",
-          type: "select",
-          label: "Role",
-          options: [
-            { value: "user", label: "User" },
-            { value: "admin", label: "Admin" },
-          ],
-        },
-        {
-          name: "notifications",
-          type: "checkbox",
-          label: "Enable notifications",
-          // Conditional field - only show for admins
-          condition: (values) => values.role === "admin",
-        },
-      ],
-    },
-  ],
-};
-```
-
-### 3. Render Your Form
-
-```tsx
-import { useForm } from "react-hook-form";
-import { FormGenerator } from "@classytic/formkit";
-import { FormProvider } from "./form-adapter";
-
-function UserForm() {
-  const form = useForm();
-
-  const onSubmit = (data: any) => {
-    console.log("Form data:", data);
-  };
-
-  return (
-    <FormProvider>
-      <form onSubmit={form.handleSubmit(onSubmit)}>
-        <FormGenerator schema={userFormSchema} control={form.control} />
-        <button type="submit">Submit</button>
-      </form>
-    </FormProvider>
-  );
-}
-```
-
-## 📖 API Reference
-
-### `<FormSystemProvider>`
-
-The root provider that registers your components.
-
-```tsx
-<FormSystemProvider components={componentsMap} layouts={layoutsMap}>
-  {children}
-</FormSystemProvider>
-```
-
-**Props:**
-- `components`: Object mapping field types to React components
-- `layouts`: Object mapping layout types to React components
-- `children`: React children
-
-### `<FormGenerator>`
-
-Renders forms from schemas.
-
-```tsx
-<FormGenerator schema={schema} control={control} disabled={false} variant="default" />
-```
-
-**Props:**
-- `schema`: Form schema object
-- `control?`: React Hook Form control (optional if inside FormProvider)
-- `disabled?`: Global disabled state
-- `variant?`: Component variant to use
-
-### Type Exports
-
-```tsx
-import type {
-  FormSchema,
-  BaseField,
-  Section,
-  FieldComponentProps,
-  ComponentRegistry,
-} from "@classytic/formkit";
-```
-
-## 🎨 Advanced Usage
-
-### Variants
-
-Support multiple UI styles:
-
-```tsx
-const components = {
-  text: DefaultInput,
-  compact: {
-    text: CompactInput,
-    select: CompactSelect,
-  },
-};
-
-// Use compact variant
-<FormGenerator schema={schema} variant="compact" />
-```
-
-### Conditional Fields
-
-```tsx
-{
-  name: "vatNumber",
-  type: "text",
-  label: "VAT Number",
-  condition: (values) => values.country === "EU",
-}
-```
-
-### Custom Renderers
-
-```tsx
-{
-  title: "Custom Section",
-  render: ({ control, disabled }) => (
-    <div>Your custom JSX here</div>
-  ),
-}
-```
-
-### Full Width Fields
-
-```tsx
-{
-  name: "description",
-  type: "textarea",
-  label: "Description",
-  fullWidth: true, // Spans all columns
-}
-```
-
-## 🧪 Testing
-
-```bash
-npm test
-```
-
-## 📄 License
-
-MIT © [Classytic](https://github.com/classytic)
-
-## 🤝 Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-## 🔗 Links
-
-- [GitHub Repository](https://github.com/classytic/formkit)
-- [Issue Tracker](https://github.com/classytic/formkit/issues)
-- [npm Package](https://www.npmjs.com/package/@classytic/formkit)
-
-## 🌟 Related Packages
-
-- [@classytic/notifications](https://www.npmjs.com/package/@classytic/notifications) - Multi-channel notification system
-- [@classytic/mongokit](https://www.npmjs.com/package/@classytic/mongokit) - Event-driven MongoDB repositories
-
+# @classytic/formkit
+
+Headless, type-safe form generation engine for React 18/19. Schema-driven with full TypeScript support.
+
+[![npm](https://img.shields.io/npm/v/@classytic/formkit.svg)](https://www.npmjs.com/package/@classytic/formkit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+
+## Features
+
+- 🎯 **Headless** - Bring your own UI components (Shadcn, MUI, Chakra, etc.)
+- 📝 **Schema-driven** - Define forms with JSON/TypeScript schemas
+- 🔒 **Type-safe** - Full TypeScript support with generics
+- ⚡ **React Hook Form** - Built on top of the best form library
+- 🎨 **Variants** - Support for multiple component variants
+- 🔀 **Conditional fields** - Show/hide fields based on form values
+- 📱 **Responsive layouts** - Multi-column grid layouts
+- 🪶 **Lightweight** - ~6KB minified, tree-shakeable
+
+## Installation
+
+```bash
+npm install @classytic/formkit react-hook-form
+# or
+pnpm add @classytic/formkit react-hook-form
+# or
+yarn add @classytic/formkit react-hook-form
+```
+
+## Quick Start
+
+### 1. Create Field Components
+
+Each field component wraps your UI library with `react-hook-form`'s Controller:
+
+```tsx
+// components/form/form-input.tsx
+"use client";
+
+import { Controller } from "react-hook-form";
+import type { FieldComponentProps } from "@classytic/formkit";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+
+export function FormInput({ control, name, label, placeholder, required }: FieldComponentProps) {
+  return (
+    <Controller
+      name={name}
+      control={control}
+      render={({ field, fieldState }) => (
+        <div className="space-y-2">
+          {label && (
+            <Label htmlFor={name}>
+              {label}
+              {required && <span className="text-red-500 ml-1">*</span>}
+            </Label>
+          )}
+          <Input {...field} id={name} placeholder={placeholder} />
+          {fieldState.error && (
+            <p className="text-sm text-red-500">{fieldState.error.message}</p>
+          )}
+        </div>
+      )}
+    />
+  );
+}
+```
+
+### 2. Create Form Adapter
+
+Register your components and layouts:
+
+```tsx
+// lib/form-adapter.tsx
+"use client";
+
+import { FormSystemProvider, type ComponentRegistry, type LayoutRegistry } from "@classytic/formkit";
+import { FormInput } from "@/components/form/form-input";
+
+const components: ComponentRegistry = {
+  text: FormInput,
+  email: FormInput,
+  password: FormInput,
+  // Add more field types...
+};
+
+const layouts: LayoutRegistry = {
+  section: ({ title, description, children }) => (
+    <div className="space-y-4">
+      {title && <h3 className="text-lg font-semibold">{title}</h3>}
+      {description && <p className="text-muted-foreground">{description}</p>}
+      {children}
+    </div>
+  ),
+  grid: ({ children, cols = 1 }) => (
+    <div className={`grid grid-cols-${cols} gap-4`}>{children}</div>
+  ),
+};
+
+export function FormProvider({ children }: { children: React.ReactNode }) {
+  return (
+    <FormSystemProvider components={components} layouts={layouts}>
+      {children}
+    </FormSystemProvider>
+  );
+}
+```
+
+### 3. Use FormGenerator
+
+```tsx
+// app/signup/page.tsx
+"use client";
+
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+import { FormGenerator, type FormSchema } from "@classytic/formkit";
+import { FormProvider } from "@/lib/form-adapter";
+
+// Validation schema
+const signupSchema = z.object({
+  firstName: z.string().min(2),
+  lastName: z.string().min(2),
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+
+type SignupData = z.infer<typeof signupSchema>;
+
+// Form schema (type-safe!)
+const formSchema: FormSchema<SignupData> = {
+  sections: [
+    {
+      title: "Personal Information",
+      cols: 2,
+      fields: [
+        { name: "firstName", type: "text", label: "First Name", required: true },
+        { name: "lastName", type: "text", label: "Last Name", required: true },
+      ],
+    },
+    {
+      title: "Account",
+      fields: [
+        { name: "email", type: "email", label: "Email", required: true },
+        { name: "password", type: "password", label: "Password", required: true },
+      ],
+    },
+  ],
+};
+
+export default function SignupPage() {
+  const form = useForm<SignupData>({
+    resolver: zodResolver(signupSchema),
+  });
+
+  return (
+    <FormProvider>
+      <form onSubmit={form.handleSubmit(console.log)} className="space-y-8">
+        <FormGenerator schema={formSchema} control={form.control} />
+        <button type="submit">Sign Up</button>
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+## API Reference
+
+### FormGenerator
+
+The main component that renders forms from a schema.
+
+```tsx
+<FormGenerator
+  schema={formSchema}      // Required: Form schema
+  control={form.control}   // Required: React Hook Form control
+  disabled={false}         // Optional: Disable all fields
+  variant="default"        // Optional: Global variant
+  className="my-form"      // Optional: Root element class
+/>
+```
+
+### FormSchema
+
+```tsx
+interface FormSchema<T extends FieldValues = FieldValues> {
+  sections: Section<T>[];
+}
+
+interface Section<T> {
+  id?: string;              // Unique identifier
+  title?: string;           // Section title
+  description?: string;     // Section description
+  icon?: ReactNode;         // Section icon
+  fields?: BaseField<T>[];  // Fields in this section
+  cols?: number;            // Grid columns (1-6)
+  gap?: number;             // Grid gap
+  variant?: string;         // Section variant
+  className?: string;       // Custom class
+  collapsible?: boolean;    // Make section collapsible
+  defaultCollapsed?: boolean;
+  condition?: (control) => boolean;  // Conditional rendering
+  render?: (props) => ReactNode;     // Custom render function
+}
+```
+
+### BaseField
+
+```tsx
+interface BaseField<T> {
+  name: string;             // Field name (required)
+  type: FieldType;          // Field type (required)
+  label?: string;           // Field label
+  placeholder?: string;     // Placeholder text
+  helperText?: string;      // Helper text below field
+  disabled?: boolean;       // Disable field
+  required?: boolean;       // Mark as required
+  readOnly?: boolean;       // Read-only field
+  variant?: string;         // Field variant
+  fullWidth?: boolean;      // Span full grid width
+  className?: string;       // Custom class
+  defaultValue?: unknown;   // Default value
+  
+  // Conditional rendering
+  condition?: (formValues: T) => boolean;
+  
+  // For select/radio/checkbox
+  options?: FieldOption[];
+  
+  // HTML input attributes
+  min?: number | string;
+  max?: number | string;
+  step?: number;
+  pattern?: string;
+  minLength?: number;
+  maxLength?: number;
+  rows?: number;           // For textarea
+  multiple?: boolean;      // For select/file
+  accept?: string;         // For file input
+  autoComplete?: string;
+  autoFocus?: boolean;
+  
+  // Custom props
+  [key: string]: unknown;
+}
+```
+
+### FieldComponentProps
+
+Props passed to your field components:
+
+```tsx
+interface FieldComponentProps<T extends FieldValues = FieldValues> extends BaseField<T> {
+  field: BaseField<T>;     // Full field config
+  control: Control<T>;     // React Hook Form control
+  disabled?: boolean;      // Merged disabled state
+  variant?: string;        // Active variant
+}
+```
+
+### ComponentRegistry
+
+```tsx
+const components: ComponentRegistry = {
+  // Simple mapping
+  text: FormInput,
+  select: FormSelect,
+  
+  // Variant-specific components
+  compact: {
+    text: CompactInput,
+    select: CompactSelect,
+  },
+};
+```
+
+### LayoutRegistry
+
+```tsx
+const layouts: LayoutRegistry = {
+  section: SectionLayout,
+  grid: GridLayout,
+  
+  // Variant-specific layouts
+  compact: {
+    section: CompactSection,
+  },
+};
+```
+
+## Advanced Features
+
+### Conditional Fields
+
+```tsx
+{
+  name: "companyName",
+  type: "text",
+  label: "Company Name",
+  condition: (values) => values.accountType === "business",
+}
+```
+
+### Variants
+
+Apply different styles based on context:
+
+```tsx
+// Register variant-specific components
+const components = {
+  text: DefaultInput,
+  compact: {
+    text: CompactInput,
+  },
+};
+
+// Use variant in schema
+const schema = {
+  sections: [{
+    variant: "compact",  // All fields use compact variant
+    fields: [...]
+  }]
+};
+
+// Or per-field
+{
+  name: "notes",
+  type: "text",
+  variant: "compact",
+}
+```
+
+### Custom Section Render
+
+```tsx
+{
+  title: "Payment",
+  render: ({ control, disabled }) => (
+    <StripeElements>
+      <CardElement />
+      <FormInput name="billingName" control={control} />
+    </StripeElements>
+  ),
+}
+```
+
+### Grouped Select Options
+
+```tsx
+{
+  name: "country",
+  type: "select",
+  options: [
+    {
+      label: "North America",
+      options: [
+        { value: "us", label: "United States" },
+        { value: "ca", label: "Canada" },
+      ],
+    },
+    {
+      label: "Europe",
+      options: [
+        { value: "uk", label: "United Kingdom" },
+        { value: "de", label: "Germany" },
+      ],
+    },
+  ],
+}
+```
+
+## Type Exports
+
+```tsx
+import type {
+  // Core
+  FormSchema,
+  FormGeneratorProps,
+  BaseField,
+  Section,
+  
+  // Components
+  FieldComponentProps,
+  FieldComponent,
+  ComponentRegistry,
+  
+  // Layouts
+  SectionLayoutProps,
+  GridLayoutProps,
+  LayoutComponent,
+  LayoutRegistry,
+  
+  // Options
+  FieldOption,
+  FieldOptionGroup,
+  
+  // Utility types
+  FieldType,
+  LayoutType,
+  Variant,
+  DefineField,
+  InferSchemaValues,
+  SchemaFieldNames,
+} from "@classytic/formkit";
+```
+
+## Examples
+
+See the [`example/shadcn`](./example/shadcn) directory for complete working examples with:
+
+- Form components (Input, Select, Checkbox)
+- Full adapter configuration
+- Zod validation
+- Conditional fields
+- Multi-column layouts
+- TypeScript integration
+
+## Browser Support
+
+- React 18.0+
+- React 19.0+
+- All modern browsers
+
+## License
+
+MIT © [Classytic](https://github.com/classytic)
+
+## Links
+
+- [GitHub](https://github.com/classytic/formkit)
+- [npm](https://www.npmjs.com/package/@classytic/formkit)
+- [Examples](https://github.com/classytic/formkit/tree/main/example/shadcn)
+- [Issues](https://github.com/classytic/formkit/issues)