@classytic/formkit 1.0.2 → 1.2.0

package/dist/index.d.mts

@@ -0,0 +1,914 @@
+"use client";
+import { ComponentType, JSX, ReactNode, Ref } from "react";
+import { Control, FieldError, FieldValues, Path, RegisterOptions, UseFormProps, UseFormReturn } from "react-hook-form";
+import { ClassValue } from "clsx";
+
+//#region src/types.d.ts
+/**
+ * Field type identifier.
+ * Can be built-in types or custom string identifiers.
+ */
+type FieldType = "text" | "email" | "password" | "number" | "tel" | "url" | "textarea" | "select" | "checkbox" | "radio" | "switch" | "date" | "time" | "datetime" | "file" | "hidden" | "group" | "array" | "custom" | (string & {});
+/**
+ * Layout type identifier.
+ */
+type LayoutType = "section" | "grid" | "default" | (string & {});
+/**
+ * Variant identifier for component styling.
+ */
+type Variant = "default" | "compact" | "inline" | (string & {}) | undefined;
+interface ConditionRule<TFieldValues extends FieldValues = FieldValues> {
+  watch: Path<TFieldValues>;
+  operator: "===" | "!==" | "in" | "not-in" | "truthy" | "falsy";
+  value?: unknown;
+}
+/**
+ * Condition configuration with explicit logic operator.
+ * Allows combining rules with AND or OR logic.
+ *
+ * @example
+ * ```ts
+ * // Show field if country is "US" OR "CA"
+ * condition: {
+ *   rules: [
+ *     { watch: "country", operator: "===", value: "US" },
+ *     { watch: "country", operator: "===", value: "CA" },
+ *   ],
+ *   logic: "or",
+ * }
+ * ```
+ */
+interface ConditionConfig<TFieldValues extends FieldValues = FieldValues> {
+  /** Array of condition rules to evaluate */
+  rules: ConditionRule<TFieldValues>[];
+  /** Logic operator: "and" (all must match) or "or" (any must match). Defaults to "and". */
+  logic?: "and" | "or";
+}
+/**
+ * Single option for select/radio/checkbox fields.
+ */
+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 in grid */
+  fullWidth?: boolean;
+  /** Custom CSS class name */
+  className?: string;
+  /**
+   * Conditional rendering function, declarative rules, or a condition config with logic.
+   * Return true to show the field, false to hide.
+   */
+  condition?: ((formValues: Partial<TFieldValues>) => boolean) | ConditionRule<TFieldValues> | ConditionRule<TFieldValues>[] | ConditionConfig<TFieldValues>;
+  /** Default value */
+  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;
+  /** Debounce loadOptions requests in milliseconds, helps prevent API storms */
+  debounceMs?: number;
+  /**
+   * Dynamic options loaded based on current form values.
+   * Useful for dependent selects (e.g., state depends on country).
+   */
+  loadOptions?: (formValues: Partial<TFieldValues>) => Promise<(FieldOption | FieldOptionGroup)[]> | (FieldOption | FieldOptionGroup)[];
+  /**
+   * Error callback for loadOptions failures.
+   * Called when loadOptions rejects. Defaults to console.error.
+   */
+  onLoadError?: (error: unknown) => void;
+  /**
+   * Fields for array or object types.
+   * Useful for 'array' or 'group' field types that need a sub-schema.
+   */
+  itemFields?: BaseField<TFieldValues>[];
+  /**
+   * Custom render function to override the component registry for this specific field.
+   * Completely bypasses the globally registered FieldComponent for this type.
+   */
+  render?: (props: FieldComponentProps<TFieldValues>) => ReactNode;
+  /**
+   * Cross-field validation function.
+   * Receives the field value and all form values for cross-field checks.
+   * Return `true` for valid, or a string error message for invalid.
+   *
+   * @example
+   * ```ts
+   * validate: (value, formValues) =>
+   *   value > formValues.minPrice || "Must be greater than min price"
+   * ```
+   */
+  validate?: (value: unknown, formValues: Partial<TFieldValues>) => string | true;
+  /**
+   * Dependencies for optimizing conditionally rendered fields.
+   * Allows specifying specific field names to watch, preventing full form re-renders.
+   */
+  watchNames?: Path<TFieldValues> | Path<TFieldValues>[];
+  /** Additional field-specific props for custom components */
+  customProps?: Record<string, unknown>;
+}
+/**
+ * Props passed to field components.
+ *
+ * Components receive both:
+ * 1. A `field` object with the complete field configuration
+ * 2. All field properties spread at the top level
+ *
+ * @template TFieldValues - Form field values type
+ *
+ * @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> extends BaseField<TFieldValues> {
+  /** Field configuration object (contains all field props) */
+  field: BaseField<TFieldValues>;
+  /** React Hook Form control for Controller integration */
+  control: Control<TFieldValues>;
+  /** Whether field is globally disabled */
+  disabled?: boolean;
+  /** Component variant */
+  variant?: Variant;
+  /** Field validation error from react-hook-form */
+  error?: FieldError;
+  /** Field state from react-hook-form */
+  fieldState?: {
+    invalid: boolean;
+    isDirty: boolean;
+    isTouched: boolean;
+    isValidating: boolean;
+    error?: FieldError;
+  };
+  /** Generated field ID for label-input association (e.g. `formkit-field-email`) */
+  fieldId: string;
+  /** Whether dynamic options are currently loading */
+  isLoading?: boolean;
+}
+/**
+ * Field component type.
+ * A React component that renders a form field.
+ */
+type FieldComponent<TFieldValues extends FieldValues = FieldValues> = ComponentType<FieldComponentProps<TFieldValues>>;
+/**
+ * Validation rules compatible with react-hook-form's RegisterOptions.
+ * Returned by `buildValidationRules()`.
+ */
+type ValidationRules = Pick<RegisterOptions, "required" | "min" | "max" | "minLength" | "maxLength" | "pattern" | "validate">;
+/**
+ * Section configuration for grouping fields.
+ * @template TFieldValues - Form field values type
+ */
+interface Section<TFieldValues extends FieldValues = FieldValues> {
+  /** Unique section identifier */
+  id?: string;
+  /** Section title */
+  title?: string;
+  /** Section description */
+  description?: string;
+  /** Section icon */
+  icon?: ReactNode;
+  /** Namespace to prepend to all field names in this section */
+  nameSpace?: string;
+  /** 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, declarative rules, or a condition config with logic.
+   * Return true to show the section, false to hide.
+   */
+  condition?: ((formValues?: Partial<TFieldValues>) => boolean) | ConditionRule<TFieldValues> | ConditionRule<TFieldValues>[] | ConditionConfig<TFieldValues>;
+  /** Whether section is collapsible */
+  collapsible?: boolean;
+  /** Default collapsed state */
+  defaultCollapsed?: boolean;
+}
+/**
+ * Props passed to section render function.
+ */
+interface SectionRenderProps<TFieldValues extends FieldValues = FieldValues> {
+  control?: Control<TFieldValues>;
+  disabled?: boolean;
+  section: Section<TFieldValues>;
+}
+/**
+ * Section layout component props.
+ */
+interface SectionLayoutProps {
+  /** Section title */
+  title?: string;
+  /** Section description */
+  description?: string;
+  /** Section icon */
+  icon?: ReactNode;
+  /** Layout variant */
+  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.
+ */
+interface GridLayoutProps {
+  /** Number of columns */
+  cols?: number;
+  /** Gap between items */
+  gap?: number;
+  /** Custom CSS class name */
+  className?: string;
+  /** Children content */
+  children: ReactNode;
+}
+/**
+ * Default layout component props.
+ */
+interface DefaultLayoutProps {
+  /** Custom CSS class name */
+  className?: string;
+  /** Children content */
+  children: ReactNode;
+}
+/**
+ * Union of all layout component props.
+ */
+type LayoutComponentProps = SectionLayoutProps | GridLayoutProps | DefaultLayoutProps;
+/**
+ * Layout component type.
+ */
+type LayoutComponent<TProps extends LayoutComponentProps = LayoutComponentProps> = ComponentType<TProps>;
+/**
+ * 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<FieldValues> | ComponentRegistry;
+}
+/**
+ * Layout registry mapping layout types to components.
+ * Supports variant-specific layouts via nested objects.
+ */
+interface LayoutRegistry {
+  [key: string]: LayoutComponent<SectionLayoutProps | GridLayoutProps | DefaultLayoutProps> | LayoutRegistry;
+}
+/**
+ * Form system context value.
+ */
+interface FormSystemContextValue {
+  /** Registered field components */
+  components: ComponentRegistry;
+  /** Registered layout components */
+  layouts: LayoutRegistry;
+}
+/**
+ * Form system provider props.
+ */
+interface FormSystemProviderProps {
+  /** Field component registry */
+  components?: ComponentRegistry;
+  /** Layout component registry */
+  layouts?: LayoutRegistry;
+  /** Children content */
+  children: ReactNode;
+}
+/**
+ * FormGenerator component props.
+ * @template TFieldValues - Form field values type
+ */
+interface FormGeneratorProps<TFieldValues extends FieldValues = FieldValues> {
+  /** Form schema defining sections and fields */
+  schema: FormSchema<TFieldValues>;
+  /** React Hook Form control object */
+  control?: Control<TFieldValues>;
+  /** Global disabled state for all fields */
+  disabled?: boolean;
+  /** Global variant for all components */
+  variant?: Variant;
+  /** Additional CSS class for the root element */
+  className?: string;
+  /** Ref to the root FormKit div element (React 19 ref-as-prop) */
+  ref?: Ref<HTMLDivElement>;
+}
+/**
+ * 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;
+//#endregion
+//#region src/FormGenerator.d.ts
+/**
+ * FormGenerator - Headless Form Generator Component
+ *
+ * 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 for type safety
+ *
+ * @example
+ * ```tsx
+ * import { useFormKit, FormGenerator } from '@classytic/formkit';
+ *
+ * const { handleSubmit, generatorProps } = useFormKit({
+ *   schema: formSchema,
+ *   resolver: zodResolver(validationSchema),
+ * });
+ *
+ * return (
+ *   <form onSubmit={handleSubmit(onSubmit)}>
+ *     <FormGenerator {...generatorProps} />
+ *   </form>
+ * );
+ * ```
+ */
+declare function FormGenerator<TFieldValues extends FieldValues = FieldValues>({
+  schema,
+  control,
+  disabled,
+  variant,
+  className,
+  ref
+}: 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.
+ */
+declare function SectionRenderer<TFieldValues extends FieldValues = FieldValues>(props: 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.
+ * If the field requires conditional logic or dynamic options, it uses the Dynamic wrapper.
+ * Otherwise, it uses the Static wrapper, vastly improving performance by skipping `useWatch`.
+ */
+declare function FieldWrapper<TFieldValues extends FieldValues = FieldValues>(props: FieldWrapperProps<TFieldValues>): FormElement;
+//#endregion
+//#region src/FormSystemContext.d.ts
+/**
+ * FormSystemProvider
+ *
+ * Root provider that enables the form system. Provides component and layout
+ * registries to FormGenerator and its descendants.
+ *
+ * @example
+ * ```tsx
+ * import { FormSystemProvider } from '@classytic/formkit';
+ *
+ * const components = {
+ *   text: TextInput,
+ *   select: SelectInput,
+ *   // Variant-specific components
+ *   compact: {
+ *     text: CompactTextInput,
+ *   },
+ * };
+ *
+ * const layouts = {
+ *   section: SectionLayout,
+ *   grid: GridLayout,
+ * };
+ *
+ * function App() {
+ *   return (
+ *     <FormSystemProvider components={components} layouts={layouts}>
+ *       <YourFormComponent />
+ *     </FormSystemProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function FormSystemProvider({
+  components,
+  layouts,
+  children
+}: FormSystemProviderProps): FormElement;
+/**
+ * Hook to access the form system context.
+ *
+ * @throws {Error} If used outside FormSystemProvider
+ * @returns Form system context value
+ *
+ * @example
+ * ```tsx
+ * const { components, layouts } = useFormSystem();
+ * ```
+ */
+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>;
+//#endregion
+//#region src/utils.d.ts
+/**
+ * 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
+ *
+ * @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;
+/**
+ * Shallow equality check for arrays and primitives.
+ * Used to stabilize useWatch output without JSON.stringify overhead.
+ */
+declare function shallowEqual(a: unknown, b: unknown): boolean;
+//#endregion
+//#region src/schema.d.ts
+/**
+ * All supported condition shapes.
+ */
+type Condition<TFieldValues extends FieldValues = FieldValues> = ((formValues: Partial<TFieldValues>) => boolean) | ConditionRule<TFieldValues> | ConditionRule<TFieldValues>[] | ConditionConfig<TFieldValues> | undefined;
+/**
+ * Evaluates a conditional rule, array of rules, or a ConditionConfig against form values.
+ * Supports AND (default) and OR logic via ConditionConfig.
+ *
+ * @param condition - The condition function, rule(s), or config
+ * @param formValues - The form values to evaluate against
+ * @returns boolean indicating if condition matches
+ */
+declare function evaluateCondition<TFieldValues extends FieldValues = FieldValues>(condition: Condition<TFieldValues>, formValues: Partial<TFieldValues>): boolean;
+/**
+ * Extracts all watch names from a condition to optimize `useWatch`.
+ * Handles single rules, arrays, and ConditionConfig objects.
+ */
+declare function extractWatchNames<TFieldValues extends FieldValues = FieldValues>(condition: Condition<TFieldValues>): string[];
+/**
+ * Strictly types a comprehensive form schema, granting exact intellisense bounds across conditions and nested watches.
+ */
+declare function defineSchema<TFieldValues extends FieldValues = FieldValues>(schema: FormSchema<TFieldValues>): FormSchema<TFieldValues>;
+/**
+ * Standard utility to strictly type a standalone field out-of-bounds, useful for externalizing massive schema structures.
+ */
+declare function defineField<TFieldValues extends FieldValues = FieldValues>(field: BaseField<TFieldValues>): BaseField<TFieldValues>;
+/**
+ * Standard utility to strictly type a standalone logic section layout block.
+ */
+declare function defineSection<TFieldValues extends FieldValues = FieldValues>(section: Section<TFieldValues>): Section<TFieldValues>;
+/**
+ * Extracts default values from a form schema.
+ * Walks all sections and fields, respecting nameSpace prefixes and group nesting.
+ *
+ * @example
+ * ```ts
+ * const defaults = extractDefaultValues(schema);
+ * const form = useForm({ defaultValues: defaults });
+ * ```
+ */
+declare function extractDefaultValues<TFieldValues extends FieldValues = FieldValues>(schema: FormSchema<TFieldValues>): Partial<TFieldValues>;
+/**
+ * Generates react-hook-form `RegisterOptions`-compatible validation rules
+ * from a field's schema props. Maps `required`, `min`, `max`, `minLength`,
+ * `maxLength`, `pattern`, and `validate` to RHF rules.
+ *
+ * @example
+ * ```tsx
+ * import { buildValidationRules } from '@classytic/formkit';
+ *
+ * function FormInput({ field, control }: FieldComponentProps) {
+ *   const rules = buildValidationRules(field);
+ *   return <Controller name={field.name} control={control} rules={rules} render={...} />;
+ * }
+ * ```
+ */
+declare function buildValidationRules<TFieldValues extends FieldValues = FieldValues>(field: BaseField<TFieldValues>): ValidationRules;
+//#endregion
+//#region src/builders.d.ts
+/**
+ * Additional field props for builder helpers.
+ * Accepts all BaseField properties except `name`, `type`, and `label`
+ * which are set by the builder method.
+ */
+type FieldProps<TFieldValues extends FieldValues = FieldValues> = Omit<BaseField<TFieldValues>, "name" | "type" | "label"> & {
+  /** Grid column class (e.g., "col-span-2") */gridColumn?: string; /** Icon for the left side of input */
+  iconLeft?: ReactNode; /** Icon for the right side of input */
+  iconRight?: ReactNode; /** Additional custom props */
+  [key: string]: unknown;
+};
+/**
+ * Section configuration props.
+ */
+interface SectionProps<TFieldValues extends FieldValues = FieldValues> extends Omit<Section<TFieldValues>, "id" | "title" | "fields" | "cols"> {
+  cols?: number;
+}
+/**
+ * Render function for custom field types.
+ */
+type CustomRenderFn = (props: {
+  control: Control<FieldValues>;
+  disabled?: boolean;
+  error?: FieldError;
+}) => ReactNode;
+/**
+ * Type-safe field builder helpers for schema-driven forms.
+ *
+ * Provides shorthand methods for common field types with sensible defaults,
+ * reducing boilerplate while maintaining full type safety.
+ *
+ * @example
+ * ```ts
+ * import { field, section } from '@classytic/formkit';
+ *
+ * const schema = {
+ *   sections: [
+ *     section("personal", "Personal Info", [
+ *       field.text("firstName", "First Name", { required: true }),
+ *       field.email("email", "Email"),
+ *       field.select("role", "Role", [
+ *         { label: "Admin", value: "admin" },
+ *         { label: "User", value: "user" },
+ *       ]),
+ *     ], { cols: 2 }),
+ *   ],
+ * };
+ * ```
+ */
+declare const field: {
+  /**
+   * Text input field.
+   */
+  text: (name: string, label: string, props?: FieldProps) => BaseField;
+  /**
+   * Email input field with default placeholder.
+   */
+  email: (name: string, label: string, props?: FieldProps) => BaseField;
+  /**
+   * URL input field with default placeholder.
+   */
+  url: (name: string, label: string, props?: FieldProps) => BaseField;
+  /**
+   * Phone/tel input field with default placeholder.
+   */
+  tel: (name: string, label: string, props?: FieldProps) => BaseField;
+  /**
+   * Password input field.
+   */
+  password: (name: string, label: string, props?: FieldProps) => BaseField;
+  /**
+   * Number input field with min: 0 default.
+   */
+  number: (name: string, label: string, props?: FieldProps) => BaseField;
+  /**
+   * Textarea field with default 3 rows.
+   */
+  textarea: (name: string, label: string, props?: FieldProps) => BaseField;
+  /**
+   * Select dropdown field.
+   */
+  select: (name: string, label: string, options: (FieldOption | FieldOptionGroup)[], props?: FieldProps) => BaseField;
+  /**
+   * Searchable combobox field.
+   */
+  combobox: (name: string, label: string, options: (FieldOption | FieldOptionGroup)[], props?: FieldProps) => BaseField;
+  /**
+   * Multi-select field (tag choice).
+   */
+  multiselect: (name: string, label: string, options: (FieldOption | FieldOptionGroup)[], props?: FieldProps) => BaseField;
+  /**
+   * Dependent select field that reacts to parent field changes.
+   */
+  dependentSelect: (name: string, label: string, props?: FieldProps) => BaseField;
+  /**
+   * Switch/toggle field.
+   */
+  switch: (name: string, label: string, props?: FieldProps) => BaseField;
+  /**
+   * Boolean field (alias for switch).
+   */
+  boolean: (name: string, label: string, props?: FieldProps) => BaseField;
+  /**
+   * Checkbox field.
+   */
+  checkbox: (name: string, label: string, props?: FieldProps) => BaseField;
+  /**
+   * Radio button group field.
+   */
+  radio: (name: string, label: string, options: FieldOption[], props?: FieldProps) => BaseField;
+  /**
+   * Date picker field.
+   */
+  date: (name: string, label: string, props?: FieldProps) => BaseField;
+  /**
+   * Tag input field with default placeholder.
+   */
+  tags: (name: string, label: string, props?: FieldProps) => BaseField;
+  /**
+   * Slug field with auto-generation from source value.
+   */
+  slug: (name: string, label: string, props?: FieldProps) => BaseField;
+  /**
+   * File upload field.
+   */
+  file: (name: string, label: string, props?: FieldProps) => BaseField;
+  /**
+   * Hidden field (no UI).
+   */
+  hidden: (name: string, props?: FieldProps) => BaseField;
+  /**
+   * Group field for nested objects.
+   * Renders itemFields as a sub-grid within the form.
+   *
+   * @example
+   * ```ts
+   * field.group("address", "Address", [
+   *   field.text("street", "Street"),
+   *   field.text("city", "City"),
+   *   field.text("zip", "ZIP Code"),
+   * ], { cols: 3 })
+   * ```
+   */
+  group: (name: string, label: string, itemFields: BaseField[], props?: FieldProps) => BaseField;
+  /**
+   * Array/repeatable field.
+   * Renders a dynamic list of sub-forms using react-hook-form's useFieldArray.
+   *
+   * @example
+   * ```ts
+   * field.array("contacts", "Contacts", [
+   *   field.text("name", "Name"),
+   *   field.email("email", "Email"),
+   * ])
+   * ```
+   */
+  array: (name: string, label: string, itemFields: BaseField[], props?: FieldProps) => BaseField;
+  /**
+   * Custom field with a render function.
+   * Bypasses the component registry entirely.
+   *
+   * @example
+   * ```ts
+   * field.custom("skills", "Skills", ({ control, disabled }) => (
+   *   <SkillSelector control={control} disabled={disabled} />
+   * ))
+   * ```
+   */
+  custom: (name: string, label: string, render: CustomRenderFn, props?: FieldProps) => BaseField;
+};
+/**
+ * Create a section definition with sensible defaults.
+ *
+ * @param id - Unique section identifier
+ * @param title - Section title
+ * @param fields - Array of field definitions
+ * @param props - Additional section configuration
+ *
+ * @example
+ * ```ts
+ * section("personal", "Personal Info", [
+ *   field.text("name", "Name", { required: true }),
+ *   field.email("email", "Email"),
+ * ], { cols: 2, variant: "card" })
+ * ```
+ */
+declare function section<TFieldValues extends FieldValues = FieldValues>(id: string, title: string, fields: BaseField<TFieldValues>[], props?: SectionProps<TFieldValues>): Section<TFieldValues>;
+/**
+ * Create a section without a title (transparent section).
+ * Useful for grouping fields without visual separation.
+ */
+declare function sectionUntitled<TFieldValues extends FieldValues = FieldValues>(fields: BaseField<TFieldValues>[], props?: Omit<SectionProps<TFieldValues>, "variant">): Section<TFieldValues>;
+//#endregion
+//#region src/useFormKit.d.ts
+/**
+ * Options for the useFormKit hook.
+ * Extends react-hook-form's UseFormProps with schema-driven defaults.
+ */
+interface UseFormKitOptions<TFieldValues extends FieldValues = FieldValues> extends Omit<UseFormProps<TFieldValues>, "defaultValues"> {
+  /** Form schema defining sections and fields */
+  schema: FormSchema<TFieldValues>;
+  /** Override or extend default values extracted from schema */
+  defaultValues?: UseFormProps<TFieldValues>["defaultValues"];
+  /** Disable all fields */
+  disabled?: boolean;
+  /** Global variant */
+  variant?: Variant;
+  /** Root element className */
+  className?: string;
+}
+/**
+ * Return value from useFormKit.
+ * Includes all useForm methods plus pre-built generatorProps.
+ */
+interface UseFormKitReturn<TFieldValues extends FieldValues = FieldValues> extends UseFormReturn<TFieldValues> {
+  /** Props to spread onto <FormGenerator /> */
+  generatorProps: Pick<FormGeneratorProps<TFieldValues>, "schema" | "control" | "disabled" | "variant" | "className">;
+}
+/**
+ * Convenience hook that combines schema default extraction with react-hook-form setup.
+ * Returns all useForm methods plus ready-to-spread `generatorProps`.
+ *
+ * @example
+ * ```tsx
+ * const { handleSubmit, generatorProps } = useFormKit({
+ *   schema: formSchema,
+ *   resolver: zodResolver(validationSchema),
+ * });
+ *
+ * return (
+ *   <form onSubmit={handleSubmit(onSubmit)}>
+ *     <FormGenerator {...generatorProps} />
+ *     <button type="submit">Submit</button>
+ *   </form>
+ * );
+ * ```
+ */
+declare function useFormKit<TFieldValues extends FieldValues = FieldValues>(options: UseFormKitOptions<TFieldValues>): UseFormKitReturn<TFieldValues>;
+//#endregion
+export { type BaseField, type ClassValue, type ComponentRegistry, type Condition, type ConditionConfig, type ConditionRule, 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 UseFormKitOptions, type UseFormKitReturn, type ValidationRules, type Variant, buildValidationRules, cn, defineField, defineSchema, defineSection, evaluateCondition, extractDefaultValues, extractWatchNames, field, section, sectionUntitled, shallowEqual, useFieldComponent, useFormKit, useFormSystem, useLayoutComponent };
+//# sourceMappingURL=index.d.mts.map