@classytic/formkit 1.0.3 → 1.2.2

package/README.md

@@ -1,6 +1,6 @@
 # @classytic/formkit
 
-Headless, type-safe form generation engine for React 18/19. Schema-driven with full TypeScript support.
+Headless, type-safe form generation engine for React 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)
@@ -8,14 +8,24 @@ Headless, type-safe form generation engine for React 18/19. Schema-driven with f
 
 ## 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
+- **Minimal boilerplate** - `useFormKit` hook: 5 lines to set up a complete form
+- **Headless** - Bring your own UI components (Shadcn, MUI, Chakra, etc.)
+- **Schema-driven** - Define forms with JSON/TypeScript schemas, defaults extracted automatically
+- **Type-safe** - Full TypeScript support with generics
+- **React Hook Form** - Built on top of the best form library, referentially stable return values
+- **React 19** - Uses modern React 19 patterns (Context as provider, ref as prop)
+- **Server Components** - Dedicated `@classytic/formkit/server` entry point for RSC
+- **Variants** - Support for multiple component variants
+- **Conditional fields** - Show/hide fields based on form values (function, DSL rules, AND/OR logic)
+- **Responsive layouts** - Multi-column grid layouts
+- **Accessibility** - Auto-generated `fieldId`, `error`, and `fieldState` props
+- **Validation helpers** - `buildValidationRules` generates RHF rules from schema props
+- **Lightweight** - ~7KB gzipped, tree-shakeable
+
+## Requirements
+
+- **React 19.0+** (React 18 is not supported)
+- **React Hook Form 7.55.0+**
 
 ## Installation
 
@@ -31,7 +41,7 @@ yarn add @classytic/formkit react-hook-form
 
 ### 1. Create Field Components
 
-Each field component wraps your UI library with `react-hook-form`'s Controller:
+Each field component receives `FieldComponentProps` including `error`, `fieldId`, and the full `field` config:
 
 ```tsx
 // components/form/form-input.tsx
@@ -42,23 +52,29 @@ 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) {
+export function FormInput({
+  control,
+  field,
+  label,
+  placeholder,
+  required,
+  error,
+  fieldId,
+}: FieldComponentProps) {
   return (
     <Controller
-      name={name}
+      name={field.name}
       control={control}
-      render={({ field, fieldState }) => (
+      render={({ field: rhfField }) => (
         <div className="space-y-2">
           {label && (
-            <Label htmlFor={name}>
+            <Label htmlFor={fieldId}>
               {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>
-          )}
+          <Input {...rhfField} id={fieldId} placeholder={placeholder} />
+          {error && <p className="text-sm text-red-500">{error.message}</p>}
         </div>
       )}
     />
@@ -74,7 +90,11 @@ Register your components and layouts:
 // lib/form-adapter.tsx
 "use client";
 
-import { FormSystemProvider, type ComponentRegistry, type LayoutRegistry } from "@classytic/formkit";
+import {
+  FormSystemProvider,
+  type ComponentRegistry,
+  type LayoutRegistry,
+} from "@classytic/formkit";
 import { FormInput } from "@/components/form/form-input";
 
 const components: ComponentRegistry = {
@@ -112,13 +132,11 @@ export function FormProvider({ children }: { children: React.ReactNode }) {
 // 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 { FormGenerator, useFormKit, 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),
@@ -128,36 +146,60 @@ const signupSchema = z.object({
 
 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 },
+        {
+          name: "firstName",
+          type: "text",
+          label: "First Name",
+          required: true,
+          defaultValue: "",
+        },
+        {
+          name: "lastName",
+          type: "text",
+          label: "Last Name",
+          required: true,
+          defaultValue: "",
+        },
       ],
     },
     {
       title: "Account",
       fields: [
-        { name: "email", type: "email", label: "Email", required: true },
-        { name: "password", type: "password", label: "Password", required: true },
+        {
+          name: "email",
+          type: "email",
+          label: "Email",
+          required: true,
+          defaultValue: "",
+        },
+        {
+          name: "password",
+          type: "password",
+          label: "Password",
+          required: true,
+          defaultValue: "",
+        },
       ],
     },
   ],
 };
 
 export default function SignupPage() {
-  const form = useForm<SignupData>({
+  const { handleSubmit, generatorProps } = useFormKit({
+    schema: formSchema,
     resolver: zodResolver(signupSchema),
   });
 
   return (
     <FormProvider>
-      <form onSubmit={form.handleSubmit(console.log)} className="space-y-8">
-        <FormGenerator schema={formSchema} control={form.control} />
+      <form onSubmit={handleSubmit(console.log)} className="space-y-8">
+        <FormGenerator {...generatorProps} />
         <button type="submit">Sign Up</button>
       </form>
     </FormProvider>
@@ -167,67 +209,125 @@ export default function SignupPage() {
 
 ## API Reference
 
+### useFormKit
+
+Convenience hook that combines schema default extraction with react-hook-form setup. Returns all `useForm` methods plus ready-to-spread `generatorProps`.
+
+**Referentially stable** — the return value preserves the original `useForm` object identity across re-renders, so it's safe to use in `useEffect` dependency arrays.
+
+```tsx
+import { useFormKit, FormGenerator } from "@classytic/formkit";
+
+const form = useFormKit({
+  schema: formSchema,
+  resolver: zodResolver(validationSchema), // optional
+  defaultValues: { email: "pre@fill.com" }, // optional overrides
+  disabled: false, // optional
+  variant: "compact", // optional
+  className: "my-form", // optional
+  mode: "onBlur", // any useForm option
+});
+
+const { handleSubmit, generatorProps } = form;
+
+// Safe to use in useEffect deps — form is referentially stable
+useEffect(() => {
+  if (open) form.reset(defaults);
+}, [open, form]);
+
+return (
+  <form onSubmit={handleSubmit(onSubmit)}>
+    <FormGenerator {...generatorProps} />
+    <button type="submit">Submit</button>
+  </form>
+);
+```
+
+Schema `defaultValue` fields are automatically extracted and merged with any explicit `defaultValues` you provide (explicit values take priority).
+
+`generatorProps` is memoized — it only recomputes when `schema`, `control`, `disabled`, `variant`, or `className` change.
+
 ### FormGenerator
 
-The main component that renders forms from a schema.
+The main component that renders forms from a schema. Supports React 19 `ref` as a regular prop.
 
 ```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
+  schema={formSchema} // Required: Form schema
+  control={form.control} // Optional: React Hook Form control (or wrap in <FormProvider>)
+  disabled={false} // Optional: Disable all fields
+  variant="default" // Optional: Global variant
+  className="my-form" // Optional: Root element class
+  ref={formRef} // Optional: Ref to the root <div> (React 19 ref-as-prop)
 />
 ```
 
 ### FormSchema
 
-```tsx
+```ts
 interface FormSchema<T extends FieldValues = FieldValues> {
   sections: Section<T>[];
 }
+```
+
+### Section
 
+```ts
 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
+  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
+  nameSpace?: string; // Prefix for nested object fields (e.g. "address")
+
+  // Conditional rendering (function, DSL rule, or ConditionConfig)
+  condition?: Condition<T>;
+
+  // Custom render function (bypasses grid layout)
+  render?: (props: SectionRenderProps<T>) => ReactNode;
 }
 ```
 
 ### BaseField
 
-```tsx
+```ts
 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
-  
+  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;
-  
+  condition?: Condition<T>;
+  watchNames?: string | string[]; // Optimize useWatch performance
+
+  // Dynamic options loading
+  loadOptions?: (
+    formValues: Partial<T>,
+  ) => Promise<FieldOption[]> | FieldOption[];
+  debounceMs?: number;
+
+  // For array/grouped types
+  itemFields?: BaseField<T>[];
+
   // For select/radio/checkbox
   options?: FieldOption[];
-  
+
   // HTML input attributes
   min?: number | string;
   max?: number | string;
@@ -235,14 +335,17 @@ interface BaseField<T> {
   pattern?: string;
   minLength?: number;
   maxLength?: number;
-  rows?: number;           // For textarea
-  multiple?: boolean;      // For select/file
-  accept?: string;         // For file input
+  rows?: number;
+  multiple?: boolean;
+  accept?: string;
   autoComplete?: string;
   autoFocus?: boolean;
-  
-  // Custom props
-  [key: string]: unknown;
+
+  // Custom render override
+  render?: (props: FieldComponentProps<T>) => ReactNode;
+
+  // Arbitrary extra props for custom components
+  customProps?: Record<string, unknown>;
 }
 ```
 
@@ -250,23 +353,66 @@ interface BaseField<T> {
 
 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
+```ts
+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
+  error?: FieldError; // Field error from react-hook-form
+  fieldState?: {
+    // Field state metadata
+    invalid: boolean;
+    isDirty: boolean;
+    isTouched: boolean;
+    isValidating: boolean;
+    error?: FieldError;
+  };
+  fieldId: string; // Generated ID for label-input association (e.g. "formkit-field-email")
 }
 ```
 
+### Condition Types
+
+Conditions can be a function, a DSL rule, an array of rules (AND), or a `ConditionConfig` (AND/OR):
+
+```ts
+// Function condition
+condition: (values) => values.accountType === "business"
+
+// Single DSL rule
+condition: { watch: "country", operator: "===", value: "US" }
+
+// Array of rules (AND - all must match)
+condition: [
+  { watch: "country", operator: "===", value: "US" },
+  { watch: "age", operator: "truthy" },
+]
+
+// ConditionConfig with OR logic
+condition: {
+  rules: [
+    { watch: "country", operator: "===", value: "US" },
+    { watch: "country", operator: "===", value: "CA" },
+  ],
+  logic: "or",
+}
+```
+
+**Supported operators:** `===`, `!==`, `in`, `not-in`, `truthy`, `falsy`
+
+**Nested paths:** DSL rules support dot-notation paths like `"address.city"` for nested form values.
+
 ### ComponentRegistry
 
-```tsx
+```ts
 const components: ComponentRegistry = {
   // Simple mapping
   text: FormInput,
   select: FormSelect,
-  
+
   // Variant-specific components
   compact: {
     text: CompactInput,
@@ -277,11 +423,11 @@ const components: ComponentRegistry = {
 
 ### LayoutRegistry
 
-```tsx
+```ts
 const layouts: LayoutRegistry = {
   section: SectionLayout,
   grid: GridLayout,
-  
+
   // Variant-specific layouts
   compact: {
     section: CompactSection,
@@ -289,11 +435,77 @@ const layouts: LayoutRegistry = {
 };
 ```
 
+### extractDefaultValues
+
+Extracts default values from a schema. Server-safe (no hooks).
+
+```ts
+import { extractDefaultValues } from "@classytic/formkit"; // or /server
+
+const defaults = extractDefaultValues(formSchema);
+// { firstName: "", lastName: "", email: "", password: "" }
+
+// Use with react-hook-form
+const form = useForm({ defaultValues: defaults });
+```
+
+Respects `nameSpace` prefixes and group `itemFields` defaults.
+
+### buildValidationRules
+
+Generates react-hook-form validation rules from a field's schema props. Server-safe (no hooks).
+
+```ts
+import { buildValidationRules } from "@classytic/formkit"; // or /server
+
+function FormInput({ field, control, error, fieldId }: FieldComponentProps) {
+  const rules = buildValidationRules(field);
+  return (
+    <Controller
+      name={field.name}
+      control={control}
+      rules={rules}
+      render={({ field: rhf }) => <input {...rhf} id={fieldId} />}
+    />
+  );
+}
+```
+
+Maps `required`, `min`, `max`, `minLength`, `maxLength`, and `pattern` from the field schema to RHF-compatible rules with auto-generated error messages.
+
+## Server Components
+
+The `@classytic/formkit/server` entry point exports server-safe utilities with no React hooks or client-side code:
+
+```ts
+import {
+  cn,
+  defineSchema,
+  defineField,
+  defineSection,
+  evaluateCondition,
+  extractWatchNames,
+  extractDefaultValues,
+  buildValidationRules,
+} from "@classytic/formkit/server";
+
+// Type-only imports also available
+import type {
+  FormSchema,
+  BaseField,
+  Section,
+  ConditionRule,
+  ConditionConfig,
+} from "@classytic/formkit/server";
+```
+
+Use this entry point in React Server Components to define schemas, evaluate conditions, or use `cn` without pulling in client-side code.
+
 ## Advanced Features
 
-### Conditional Fields
+### Conditional Fields (Function)
 
-```tsx
+```ts
 {
   name: "companyName",
   type: "text",
@@ -302,6 +514,73 @@ const layouts: LayoutRegistry = {
 }
 ```
 
+### Conditional Fields (DSL Rules)
+
+```ts
+{
+  name: "stateField",
+  type: "select",
+  label: "State",
+  condition: { watch: "country", operator: "===", value: "US" },
+  watchNames: ["country"], // Optimizes re-renders
+}
+```
+
+### Conditional Sections
+
+```ts
+{
+  title: "Business Details",
+  condition: (values) => values.accountType === "business",
+  fields: [
+    { name: "companyName", type: "text", label: "Company" },
+    { name: "taxId", type: "text", label: "Tax ID" },
+  ],
+}
+```
+
+### OR Conditions
+
+```ts
+{
+  name: "taxField",
+  type: "text",
+  condition: {
+    rules: [
+      { watch: "country", operator: "===", value: "US" },
+      { watch: "country", operator: "===", value: "CA" },
+    ],
+    logic: "or",
+  },
+}
+```
+
+### Nested Path Conditions
+
+DSL rules resolve dot-notation paths for nested form values:
+
+```ts
+{
+  name: "zipCode",
+  type: "text",
+  condition: { watch: "address.country", operator: "===", value: "US" },
+}
+```
+
+### Namespace Support
+
+Prefix all field names in a section with a namespace for nested objects:
+
+```ts
+{
+  nameSpace: "address",
+  fields: [
+    { name: "street", type: "text" },  // Becomes "address.street"
+    { name: "city", type: "text" },    // Becomes "address.city"
+  ],
+}
+```
+
 ### Variants
 
 Apply different styles based on context:
@@ -315,25 +594,34 @@ const components = {
   },
 };
 
-// Use variant in schema
-const schema = {
-  sections: [{
-    variant: "compact",  // All fields use compact variant
-    fields: [...]
-  }]
-};
+// Use variant on the whole form
+<FormGenerator schema={schema} variant="compact" />
+
+// Or per-section
+{ variant: "compact", fields: [...] }
 
 // Or per-field
+{ name: "notes", type: "text", variant: "compact" }
+```
+
+### Dynamic Options Loading
+
+```ts
 {
-  name: "notes",
-  type: "text",
-  variant: "compact",
+  name: "city",
+  type: "select",
+  watchNames: ["country"],
+  loadOptions: async (values) => {
+    const cities = await fetchCities(values.country);
+    return cities.map(c => ({ label: c.name, value: c.id }));
+  },
+  debounceMs: 300,
 }
 ```
 
 ### Custom Section Render
 
-```tsx
+```ts
 {
   title: "Payment",
   render: ({ control, disabled }) => (
@@ -345,9 +633,46 @@ const schema = {
 }
 ```
 
-### Grouped Select Options
+### Custom Field Render
+
+```ts
+{
+  name: "avatar",
+  type: "file",
+  render: ({ field, control, error, fieldId }) => (
+    <AvatarUploader fieldId={fieldId} error={error} />
+  ),
+}
+```
+
+### Custom Props
+
+Pass arbitrary props to your field components via `customProps`:
+
+```ts
+{
+  name: "bio",
+  type: "textarea",
+  label: "Biography",
+  customProps: {
+    maxCharacters: 500,
+    showCounter: true,
+  },
+}
+```
+
+Access in your component:
 
 ```tsx
+function FormTextarea({ field, customProps, ...props }: FieldComponentProps) {
+  const maxChars = customProps?.maxCharacters as number;
+  // ...
+}
+```
+
+### Grouped Select Options
+
+```ts
 {
   name: "country",
   type: "select",
@@ -370,31 +695,69 @@ const schema = {
 }
 ```
 
+### Schema Builder Utilities
+
+Type-safe helpers for defining schemas outside of components:
+
+```ts
+import {
+  defineSchema,
+  defineField,
+  defineSection,
+} from "@classytic/formkit/server";
+
+const emailField = defineField<MyFormData>({
+  name: "email",
+  type: "email",
+  label: "Email Address",
+  required: true,
+});
+
+const personalSection = defineSection<MyFormData>({
+  title: "Personal Info",
+  cols: 2,
+  fields: [emailField],
+});
+
+const schema = defineSchema<MyFormData>({
+  sections: [personalSection],
+});
+```
+
 ## Type Exports
 
-```tsx
+```ts
 import type {
   // Core
   FormSchema,
   FormGeneratorProps,
   BaseField,
   Section,
-  
+
   // Components
   FieldComponentProps,
   FieldComponent,
   ComponentRegistry,
-  
+
   // Layouts
   SectionLayoutProps,
   GridLayoutProps,
   LayoutComponent,
   LayoutRegistry,
-  
+
   // Options
   FieldOption,
   FieldOptionGroup,
-  
+
+  // Conditions
+  ConditionRule,
+  ConditionConfig,
+  Condition,
+
+  // Hook types
+  UseFormKitOptions,
+  UseFormKitReturn,
+
   // Utility types
   FieldType,
   LayoutType,
@@ -402,23 +765,12 @@ import type {
   DefineField,
   InferSchemaValues,
   SchemaFieldNames,
+  FormElement,
 } 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