@classytic/formkit 1.0.0 → 1.0.2

package/README.md

@@ -1,273 +1,161 @@
-# @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)
+
+## Installation
+
+```bash
+npm install @classytic/formkit react-hook-form
+```
+
+## Quick Start (Shadcn UI)
+
+**Important:** You must use `Controller` from react-hook-form. Raw Shadcn components won't work.
+
+### 1. Install Shadcn Components
+
+```bash
+npx shadcn@latest add input label select
+```
+
+### 2. Create Form Component
+
+```tsx
+// components/form-input.tsx
+import { Controller } from "react-hook-form";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+
+export function FormInput({ control, name, label, placeholder, required, ...props }) {
+  return (
+    <Controller
+      name={name}
+      control={control}
+      render={({ field, fieldState }) => (
+        <div className="space-y-2">
+          {label && <Label>{label}{required && '*'}</Label>}
+          <Input {...field} placeholder={placeholder} />
+          {fieldState.error && <p className="text-sm text-red-500">{fieldState.error.message}</p>}
+        </div>
+      )}
+    />
+  );
+}
+```
+
+### 3. Create Adapter
+
+```tsx
+// lib/form-adapter.tsx
+import { FormSystemProvider } from "@classytic/formkit";
+import { FormInput } from "@/components/form-input";
+
+const components = {
+  text: FormInput,
+  email: FormInput,
+};
+
+const layouts = {
+  section: ({ title, children }) => <div><h3>{title}</h3>{children}</div>,
+  grid: ({ children, cols = 1 }) => <div className={`grid grid-cols-${cols} gap-4`}>{children}</div>,
+};
+
+export function FormProvider({ children }) {
+  return <FormSystemProvider components={components} layouts={layouts}>{children}</FormSystemProvider>;
+}
+```
+
+### 4. Use in Your App
+
+```tsx
+import { useForm } from "react-hook-form";
+import { FormGenerator } from "@classytic/formkit";
+import { FormProvider } from "./form-adapter";
+
+export function MyForm() {
+  const form = useForm();
+
+  return (
+    <FormProvider>
+      <form onSubmit={form.handleSubmit(console.log)}>
+        <FormGenerator
+          schema={{
+            sections: [{
+              fields: [
+                { name: "email", type: "email", label: "Email", required: true },
+                { name: "password", type: "text", label: "Password" },
+              ]
+            }]
+          }}
+          control={form.control}
+        />
+        <button type="submit">Submit</button>
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+## Complete Examples
+
+See `example/shadcn/` directory for full working examples with:
+- FormInput, FormSelect, FormCheckbox
+- Validation with Zod
+- Conditional fields
+- Error handling
+
+## Key Points
+
+**You MUST use Controller:**
+```tsx
+import { Controller } from "react-hook-form";
+
+<Controller
+  name={name}
+  control={control}
+  render={({ field, fieldState }) => (
+    <Input {...field} />  // ← Spread field
+  )}
+/>
+```
+
+**Component receives these props:**
+```tsx
+{
+  field: {...},     // Config object  
+  control: {...},   // React Hook Form control
+  name: "email",    // Plus all field props spread
+  label: "Email",
+  // ...
+}
+```
+
+## API
+
+### FormGenerator
+
+| Prop | Type | Required |
+|------|------|----------|
+| schema | FormSchema | Yes |
+| control | Control | Yes |
+| disabled | boolean | No |
+| variant | string | No |
+
+### Types
+
+```tsx
+import type { FormSchema, FieldComponentProps } from "@classytic/formkit";
+```
+
+## License
+
+MIT © [Classytic](https://github.com/classytic)
+
+## Links
+
+- [GitHub](https://github.com/classytic/formkit)
+- [Examples](https://github.com/classytic/formkit/tree/main/example/shadcn)
+- [Issues](https://github.com/classytic/formkit/issues)

package/dist/index.d.cts

@@ -45,15 +45,38 @@ interface BaseField {
 }
 /**
  * Field component props
+ *
+ * IMPORTANT: Components receive both:
+ * 1. A `field` object with the complete field configuration
+ * 2. All field properties spread at the top level (via ...field)
+ *
+ * Example:
+ * ```tsx
+ * // Schema
+ * { name: "email", type: "email", label: "Email", placeholder: "user@example.com" }
+ *
+ * // Your component receives:
+ * {
+ *   field: { name: "email", type: "email", label: "Email", placeholder: "..." },
+ *   control: {...},
+ *   disabled: false,
+ *   variant: undefined,
+ *   // PLUS all field props at top level:
+ *   name: "email",
+ *   type: "email",
+ *   label: "Email",
+ *   placeholder: "user@example.com"
+ * }
+ * ```
  */
-interface FieldComponentProps<TFieldValues extends FieldValues = FieldValues> {
-    /** Field configuration */
+interface FieldComponentProps<TFieldValues extends FieldValues = FieldValues> extends BaseField {
+    /** Field configuration object (contains all field props) */
     field: BaseField;
-    /** React Hook Form control */
-    control?: Control<TFieldValues>;
-    /** Whether field is disabled */
+    /** React Hook Form control (for Controller integration) */
+    control?: Control<TFieldValues> | Control<any>;
+    /** Whether field is globally disabled */
     disabled?: boolean;
-    /** Field variant */
+    /** Component variant (e.g., "compact", "default") */
     variant?: Variant;
 }
 /**

package/dist/index.d.ts

@@ -45,15 +45,38 @@ interface BaseField {
 }
 /**
  * Field component props
+ *
+ * IMPORTANT: Components receive both:
+ * 1. A `field` object with the complete field configuration
+ * 2. All field properties spread at the top level (via ...field)
+ *
+ * Example:
+ * ```tsx
+ * // Schema
+ * { name: "email", type: "email", label: "Email", placeholder: "user@example.com" }
+ *
+ * // Your component receives:
+ * {
+ *   field: { name: "email", type: "email", label: "Email", placeholder: "..." },
+ *   control: {...},
+ *   disabled: false,
+ *   variant: undefined,
+ *   // PLUS all field props at top level:
+ *   name: "email",
+ *   type: "email",
+ *   label: "Email",
+ *   placeholder: "user@example.com"
+ * }
+ * ```
  */
-interface FieldComponentProps<TFieldValues extends FieldValues = FieldValues> {
-    /** Field configuration */
+interface FieldComponentProps<TFieldValues extends FieldValues = FieldValues> extends BaseField {
+    /** Field configuration object (contains all field props) */
     field: BaseField;
-    /** React Hook Form control */
-    control?: Control<TFieldValues>;
-    /** Whether field is disabled */
+    /** React Hook Form control (for Controller integration) */
+    control?: Control<TFieldValues> | Control<any>;
+    /** Whether field is globally disabled */
     disabled?: boolean;
-    /** Field variant */
+    /** Component variant (e.g., "compact", "default") */
     variant?: Variant;
 }
 /**

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@classytic/formkit",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Headless, type-safe form generation engine for React. Schema-driven with full TypeScript support.",
   "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     }
   },
   "files": [