@classytic/formkit 1.0.2 → 1.0.3

package/dist/index.d.ts

@@ -1,56 +1,118 @@
-import { FieldValues, Control } from 'react-hook-form';
-import { ReactNode, ComponentType } from 'react';
+import { FieldValues, Path, Control } from 'react-hook-form';
+import { ReactNode, JSX, ComponentType } from 'react';
 import { ClassValue } from 'clsx';
+export { ClassValue } from 'clsx';
 
 /**
- * Field type identifier
+ * Field type identifier.
+ * Can be built-in types or custom string identifiers.
  */
-type FieldType = string;
+type FieldType = "text" | "email" | "password" | "number" | "tel" | "url" | "textarea" | "select" | "checkbox" | "radio" | "switch" | "date" | "time" | "datetime" | "file" | "hidden" | "custom" | (string & {});
 /**
- * Layout type identifier
+ * Layout type identifier.
  */
-type LayoutType = "section" | "grid" | "default" | string;
+type LayoutType = "section" | "grid" | "default" | (string & {});
 /**
- * Variant identifier for component styling
+ * Variant identifier for component styling.
  */
-type Variant = string | undefined;
+type Variant = "default" | "compact" | "inline" | (string & {}) | undefined;
 /**
- * Base field configuration
+ * Single option for select/radio/checkbox fields.
  */
-interface BaseField {
-    /** Field name (maps to form field) */
-    name: string;
-    /** Field type (text, select, checkbox, etc.) */
+interface FieldOption<TValue = string> {
+    /** Display label */
+    label: string;
+    /** Option value */
+    value: TValue;
+    /** Whether option is disabled */
+    disabled?: boolean;
+    /** Optional description */
+    description?: string;
+    /** Optional icon */
+    icon?: ReactNode;
+}
+/**
+ * Option group for select fields.
+ */
+interface FieldOptionGroup<TValue = string> {
+    /** Group label */
+    label: string;
+    /** Group options */
+    options: FieldOption<TValue>[];
+    /** Whether group is disabled */
+    disabled?: boolean;
+}
+/**
+ * Base field configuration shared by all field types.
+ * @template TFieldValues - Form field values type for type-safe field names
+ */
+interface BaseField<TFieldValues extends FieldValues = FieldValues> {
+    /** Field name (must be a valid path in form values) */
+    name: Path<TFieldValues> | (string & {});
+    /** Field type identifier */
     type: FieldType;
     /** Field label */
     label?: string;
     /** Placeholder text */
     placeholder?: string;
+    /** Helper text shown below the field */
+    helperText?: string;
     /** Whether field is disabled */
     disabled?: boolean;
     /** Whether field is required */
     required?: boolean;
+    /** Whether field is read-only */
+    readOnly?: boolean;
     /** Field variant */
     variant?: Variant;
-    /** Whether field should span full width */
+    /** Whether field should span full width in grid */
     fullWidth?: boolean;
     /** Custom CSS class name */
     className?: string;
-    /** Conditional rendering function */
-    condition?: (formValues: FieldValues) => boolean;
+    /**
+     * Conditional rendering function.
+     * Return true to show the field, false to hide.
+     */
+    condition?: (formValues: TFieldValues) => boolean;
     /** Default value */
-    defaultValue?: any;
-    /** Additional field-specific props */
-    [key: string]: any;
+    defaultValue?: unknown;
+    /** Options for select/radio/checkbox fields */
+    options?: (FieldOption | FieldOptionGroup)[];
+    /** Minimum value (for number/date fields) */
+    min?: number | string;
+    /** Maximum value (for number/date fields) */
+    max?: number | string;
+    /** Step value (for number fields) */
+    step?: number;
+    /** Pattern for validation (regex string) */
+    pattern?: string;
+    /** Minimum length */
+    minLength?: number;
+    /** Maximum length */
+    maxLength?: number;
+    /** Number of rows (for textarea) */
+    rows?: number;
+    /** Multiple selection (for select/file) */
+    multiple?: boolean;
+    /** Accepted file types (for file input) */
+    accept?: string;
+    /** Auto-complete attribute */
+    autoComplete?: string;
+    /** Auto-focus on mount */
+    autoFocus?: boolean;
+    /** Additional field-specific props (for custom components) */
+    [key: string]: unknown;
 }
 /**
- * Field component props
+ * Props passed to field components.
  *
- * IMPORTANT: Components receive both:
+ * Components receive both:
  * 1. A `field` object with the complete field configuration
- * 2. All field properties spread at the top level (via ...field)
+ * 2. All field properties spread at the top level
+ *
+ * @template TFieldValues - Form field values type
  *
- * Example:
+ * @example
  * ```tsx
  * // Schema
  * { name: "email", type: "email", label: "Email", placeholder: "user@example.com" }
@@ -69,21 +131,27 @@ interface BaseField {
  * }
  * ```
  */
-interface FieldComponentProps<TFieldValues extends FieldValues = FieldValues> extends BaseField {
+interface FieldComponentProps<TFieldValues extends FieldValues = FieldValues> extends BaseField<TFieldValues> {
     /** Field configuration object (contains all field props) */
-    field: BaseField;
-    /** React Hook Form control (for Controller integration) */
-    control?: Control<TFieldValues> | Control<any>;
+    field: BaseField<TFieldValues>;
+    /** React Hook Form control for Controller integration */
+    control: Control<TFieldValues>;
     /** Whether field is globally disabled */
     disabled?: boolean;
-    /** Component variant (e.g., "compact", "default") */
+    /** Component variant */
     variant?: Variant;
 }
 /**
- * Section configuration
+ * Field component type.
+ * A React component that renders a form field.
+ */
+type FieldComponent<TFieldValues extends FieldValues = FieldValues> = ComponentType<FieldComponentProps<TFieldValues>>;
+/**
+ * Section configuration for grouping fields.
+ * @template TFieldValues - Form field values type
  */
-interface Section {
-    /** Section ID (optional) */
+interface Section<TFieldValues extends FieldValues = FieldValues> {
+    /** Unique section identifier */
     id?: string;
     /** Section title */
     title?: string;
@@ -91,32 +159,41 @@ interface Section {
     description?: string;
     /** Section icon */
     icon?: ReactNode;
-    /** Section fields */
-    fields?: BaseField[];
-    /** Number of columns in grid */
-    cols?: number;
-    /** Custom render function */
-    render?: (props: {
-        control?: Control<any>;
-        disabled?: boolean;
-        section: Section;
-    }) => ReactNode;
+    /** Fields in this section */
+    fields?: BaseField<TFieldValues>[];
+    /** Number of columns in grid layout */
+    cols?: 1 | 2 | 3 | 4 | 5 | 6 | number;
+    /** Gap between grid items (Tailwind spacing scale) */
+    gap?: number;
+    /**
+     * Custom render function for complete control.
+     * When provided, fields array is ignored.
+     */
+    render?: (props: SectionRenderProps<TFieldValues>) => ReactNode;
     /** Section variant */
     variant?: Variant;
     /** Custom CSS class name */
     className?: string;
-    /** Conditional rendering function */
-    condition?: (control?: Control<any>) => boolean;
+    /**
+     * Conditional rendering function.
+     * Return true to show the section, false to hide.
+     */
+    condition?: (control?: Control<TFieldValues>) => boolean;
+    /** Whether section is collapsible */
+    collapsible?: boolean;
+    /** Default collapsed state */
+    defaultCollapsed?: boolean;
 }
 /**
- * Form schema configuration
+ * Props passed to section render function.
  */
-interface FormSchema {
-    /** Form sections */
-    sections: Section[];
+interface SectionRenderProps<TFieldValues extends FieldValues = FieldValues> {
+    control?: Control<TFieldValues>;
+    disabled?: boolean;
+    section: Section<TFieldValues>;
 }
 /**
- * Section layout component props
+ * Section layout component props.
  */
 interface SectionLayoutProps {
     /** Section title */
@@ -129,44 +206,79 @@ interface SectionLayoutProps {
     variant?: Variant;
     /** Custom CSS class name */
     className?: string;
+    /** Whether section is collapsible */
+    collapsible?: boolean;
+    /** Default collapsed state */
+    defaultCollapsed?: boolean;
     /** Children content */
     children: ReactNode;
 }
 /**
- * Grid layout component props
+ * Grid layout component props.
  */
 interface GridLayoutProps {
     /** Number of columns */
     cols?: number;
+    /** Gap between items */
+    gap?: number;
+    /** Custom CSS class name */
+    className?: string;
     /** Children content */
     children: ReactNode;
 }
 /**
- * Layout component props union
+ * Default layout component props.
  */
-type LayoutComponentProps = SectionLayoutProps | GridLayoutProps;
+interface DefaultLayoutProps {
+    /** Custom CSS class name */
+    className?: string;
+    /** Children content */
+    children: ReactNode;
+}
 /**
- * Field component type
+ * Union of all layout component props.
  */
-type FieldComponent<TFieldValues extends FieldValues = FieldValues> = ComponentType<FieldComponentProps<TFieldValues>>;
+type LayoutComponentProps = SectionLayoutProps | GridLayoutProps | DefaultLayoutProps;
 /**
- * Layout component type
+ * Layout component type.
  */
-type LayoutComponent = ComponentType<any>;
+type LayoutComponent<TProps extends LayoutComponentProps = LayoutComponentProps> = ComponentType<TProps>;
 /**
- * Component registry mapping field types to components
+ * Complete form schema configuration.
+ * @template TFieldValues - Form field values type for type-safe schemas
+ */
+interface FormSchema<TFieldValues extends FieldValues = FieldValues> {
+    /** Form sections */
+    sections: Section<TFieldValues>[];
+}
+/**
+ * Component registry mapping field types to components.
+ * Supports variant-specific components via nested objects.
+ *
+ * @example
+ * ```tsx
+ * const components: ComponentRegistry = {
+ *   text: TextInput,
+ *   select: SelectInput,
+ *   // Variant-specific
+ *   compact: {
+ *     text: CompactTextInput,
+ *   },
+ * };
+ * ```
  */
 interface ComponentRegistry {
-    [key: string]: FieldComponent | ComponentRegistry;
+    [key: string]: FieldComponent<FieldValues> | ComponentRegistry;
 }
 /**
- * Layout registry mapping layout types to components
+ * Layout registry mapping layout types to components.
+ * Supports variant-specific layouts via nested objects.
  */
 interface LayoutRegistry {
-    [key: string]: LayoutComponent | LayoutRegistry;
+    [key: string]: LayoutComponent<SectionLayoutProps | GridLayoutProps | DefaultLayoutProps> | LayoutRegistry;
 }
 /**
- * Form system context value
+ * Form system context value.
  */
 interface FormSystemContextValue {
     /** Registered field components */
@@ -175,7 +287,7 @@ interface FormSystemContextValue {
     layouts: LayoutRegistry;
 }
 /**
- * Form system provider props
+ * Form system provider props.
  */
 interface FormSystemProviderProps {
     /** Field component registry */
@@ -186,34 +298,61 @@ interface FormSystemProviderProps {
     children: ReactNode;
 }
 /**
- * Form generator props
+ * FormGenerator component props.
+ * @template TFieldValues - Form field values type
  */
 interface FormGeneratorProps<TFieldValues extends FieldValues = FieldValues> {
-    /** Form schema */
-    schema: FormSchema;
-    /** React Hook Form control */
+    /** Form schema defining sections and fields */
+    schema: FormSchema<TFieldValues>;
+    /** React Hook Form control object */
     control?: Control<TFieldValues>;
-    /** Global disabled state */
+    /** Global disabled state for all fields */
     disabled?: boolean;
-    /** Global variant */
+    /** Global variant for all components */
     variant?: Variant;
+    /** Additional CSS class for the root element */
+    className?: string;
 }
+/**
+ * Extract field names from a schema.
+ */
+type SchemaFieldNames<TSchema extends FormSchema> = TSchema extends FormSchema<infer T> ? keyof T : never;
+/**
+ * Infer field values type from a schema.
+ */
+type InferSchemaValues<TSchema extends FormSchema> = TSchema extends FormSchema<infer T> ? T : FieldValues;
+/**
+ * Helper type for creating type-safe field definitions.
+ */
+type DefineField<TFieldValues extends FieldValues, TType extends FieldType = FieldType> = BaseField<TFieldValues> & {
+    type: TType;
+};
+/**
+ * JSX Element return type for components.
+ */
+type FormElement = JSX.Element | null;
 
 /**
  * FormGenerator - Headless Form Generator Component
  *
- * Renders a form based on a schema, using components injected via FormSystemProvider.
- * Supports conditional fields, dynamic layouts, and variants.
+ * Renders a form based on a schema definition, using components registered
+ * via FormSystemProvider. Supports conditional fields, dynamic layouts,
+ * and component variants.
  *
- * @template TFieldValues - Form field values type
+ * @template TFieldValues - Form field values type for type safety
  *
  * @example
  * ```tsx
  * import { useForm } from 'react-hook-form';
  * import { FormGenerator } from '@classytic/formkit';
  *
+ * interface FormData {
+ *   firstName: string;
+ *   email: string;
+ * }
+ *
  * function MyForm() {
- *   const { control } = useForm();
+ *   const { control } = useForm<FormData>();
  *
  *   const schema = {
  *     sections: [
@@ -231,13 +370,47 @@ interface FormGeneratorProps<TFieldValues extends FieldValues = FieldValues> {
  * }
  * ```
  */
-declare function FormGenerator<TFieldValues extends FieldValues = FieldValues>({ schema, control, disabled, variant, }: FormGeneratorProps<TFieldValues>): JSX.Element | null;
+declare function FormGenerator<TFieldValues extends FieldValues = FieldValues>({ schema, control, disabled, variant, className, }: FormGeneratorProps<TFieldValues>): FormElement;
+interface SectionRendererProps<TFieldValues extends FieldValues = FieldValues> {
+    section: Section<TFieldValues>;
+    control?: Control<TFieldValues>;
+    disabled?: boolean;
+    variant?: Variant;
+}
+/**
+ * Renders a single section with its fields.
+ * Handles conditional rendering and variant resolution.
+ */
+declare function SectionRenderer<TFieldValues extends FieldValues = FieldValues>({ section, control, disabled, variant, }: SectionRendererProps<TFieldValues>): FormElement;
+interface GridRendererProps<TFieldValues extends FieldValues = FieldValues> {
+    fields?: BaseField<TFieldValues>[];
+    cols?: number;
+    gap?: number;
+    control?: Control<TFieldValues>;
+    disabled?: boolean;
+    variant?: Variant;
+}
+/**
+ * Renders a grid of fields with specified column layout.
+ */
+declare function GridRenderer<TFieldValues extends FieldValues = FieldValues>({ fields, cols, gap, control, disabled, variant, }: GridRendererProps<TFieldValues>): FormElement;
+interface FieldWrapperProps<TFieldValues extends FieldValues = FieldValues> {
+    field: BaseField<TFieldValues>;
+    control?: Control<TFieldValues>;
+    disabled?: boolean;
+    variant?: Variant;
+}
+/**
+ * Wraps individual fields with conditional rendering logic.
+ * Handles field visibility and variant resolution.
+ */
+declare function FieldWrapper<TFieldValues extends FieldValues = FieldValues>({ field, control, disabled, variant, }: FieldWrapperProps<TFieldValues>): FormElement;
 
 /**
  * FormSystemProvider
  *
- * Provides the component registry to the form system.
- * This is the root provider that enables FormGenerator to work.
+ * Root provider that enables the form system. Provides component and layout
+ * registries to FormGenerator and its descendants.
  *
  * @example
  * ```tsx
@@ -246,6 +419,10 @@ declare function FormGenerator<TFieldValues extends FieldValues = FieldValues>({
  * const components = {
  *   text: TextInput,
  *   select: SelectInput,
+ *   // Variant-specific components
+ *   compact: {
+ *     text: CompactTextInput,
+ *   },
  * };
  *
  * const layouts = {
@@ -262,9 +439,9 @@ declare function FormGenerator<TFieldValues extends FieldValues = FieldValues>({
  * }
  * ```
  */
-declare function FormSystemProvider({ components, layouts, children, }: FormSystemProviderProps): JSX.Element;
+declare function FormSystemProvider({ components, layouts, children, }: FormSystemProviderProps): FormElement;
 /**
- * Hook to access the form system context
+ * Hook to access the form system context.
  *
  * @throws {Error} If used outside FormSystemProvider
  * @returns Form system context value
@@ -275,14 +452,60 @@ declare function FormSystemProvider({ components, layouts, children, }: FormSyst
  * ```
  */
 declare function useFormSystem(): FormSystemContextValue;
+/**
+ * Hook to get a field component by type and optional variant.
+ *
+ * Resolution order:
+ * 1. Variant-specific component: `components[variant][type]`
+ * 2. Type-specific component: `components[type]`
+ * 3. Default component: `components["default"]`
+ * 4. Text fallback: `components["text"]`
+ *
+ * @param type - Field type identifier
+ * @param variant - Optional variant name
+ * @returns Field component or fallback
+ *
+ * @internal
+ */
+declare function useFieldComponent(type: FieldType, variant?: Variant): FieldComponent;
+/**
+ * Hook to get a layout component by type and optional variant.
+ *
+ * Resolution order:
+ * 1. Variant-specific layout: `layouts[variant][type]`
+ * 2. Type-specific layout: `layouts[type]`
+ * 3. Default layout: `layouts["default"]`
+ * 4. Built-in default layout
+ *
+ * @param type - Layout type identifier
+ * @param variant - Optional variant name
+ * @returns Layout component or fallback
+ *
+ * @internal
+ */
+declare function useLayoutComponent(type: LayoutType, variant?: Variant): LayoutComponent<SectionLayoutProps | GridLayoutProps | DefaultLayoutProps>;
 
 /**
- * Utility function to merge Tailwind CSS classes
- * Combines clsx and tailwind-merge for conflict-free class merging
+ * Utility function to merge CSS classes with Tailwind CSS conflict resolution.
+ *
+ * Combines `clsx` for conditional class handling with `tailwind-merge`
+ * for proper Tailwind CSS class conflict resolution.
+ *
+ * @param inputs - Class values to merge (strings, arrays, objects, or conditionals)
+ * @returns Merged and deduplicated class string
  *
- * @param inputs - Class values to merge
- * @returns Merged class string
+ * @example
+ * ```tsx
+ * // Basic usage
+ * cn("px-2 py-1", "px-4") // "py-1 px-4"
+ *
+ * // Conditional classes
+ * cn("base", isActive && "active", { "disabled": isDisabled })
+ *
+ * // Arrays
+ * cn(["flex", "items-center"], "gap-2")
+ * ```
  */
 declare function cn(...inputs: ClassValue[]): string;
 
-export { type BaseField, type ComponentRegistry, type FieldComponent, type FieldComponentProps, type FieldType, FormGenerator, type FormGeneratorProps, type FormSchema, type FormSystemContextValue, FormSystemProvider, type FormSystemProviderProps, type GridLayoutProps, type LayoutComponent, type LayoutComponentProps, type LayoutRegistry, type LayoutType, type Section, type SectionLayoutProps, type Variant, cn, useFormSystem };
+export { type BaseField, type ComponentRegistry, type DefaultLayoutProps, type DefineField, type FieldComponent, type FieldComponentProps, type FieldOption, type FieldOptionGroup, type FieldType, FieldWrapper, type FormElement, FormGenerator, type FormGeneratorProps, type FormSchema, type FormSystemContextValue, FormSystemProvider, type FormSystemProviderProps, type GridLayoutProps, GridRenderer, type InferSchemaValues, type LayoutComponent, type LayoutComponentProps, type LayoutRegistry, type LayoutType, type SchemaFieldNames, type Section, type SectionLayoutProps, type SectionRenderProps, SectionRenderer, type Variant, cn, useFieldComponent, useFormSystem, useLayoutComponent };