@mehdashti/forms 0.2.1 → 0.3.1

package/dist/index.d.ts

@@ -0,0 +1,634 @@
+import * as react_hook_form from 'react-hook-form';
+import { FieldValues, DefaultValues, Path, UseFormReturn, Control, ArrayPath, FieldErrors } from 'react-hook-form';
+export { FieldErrors, FieldValues, Path, PathValue } from 'react-hook-form';
+import { z, ZodTypeAny } from 'zod';
+export { z } from 'zod';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React$1 from 'react';
+
+interface SmartFormOptions<TFieldValues extends FieldValues = FieldValues> {
+    schema: z.ZodSchema<TFieldValues>;
+    onSubmit: (data: TFieldValues) => void | Promise<void>;
+    onError?: (errors: Record<string, unknown>) => void;
+    realtimeValidation?: boolean;
+    defaultValues?: DefaultValues<TFieldValues>;
+    mode?: 'onSubmit' | 'onBlur' | 'onChange' | 'onTouched' | 'all';
+}
+/**
+ * Enhanced React Hook Form with Zod validation and smart defaults
+ */
+declare function useSmartForm<TFieldValues extends FieldValues = FieldValues>(options: SmartFormOptions<TFieldValues>): {
+    handleSubmit: (e?: React.BaseSyntheticEvent) => Promise<void>;
+    isSubmitting: boolean;
+    hasErrors: boolean;
+    getError: (name: Path<TFieldValues>) => string | undefined;
+    watch: react_hook_form.UseFormWatch<TFieldValues>;
+    getValues: react_hook_form.UseFormGetValues<TFieldValues>;
+    getFieldState: react_hook_form.UseFormGetFieldState<TFieldValues>;
+    setError: react_hook_form.UseFormSetError<TFieldValues>;
+    clearErrors: react_hook_form.UseFormClearErrors<TFieldValues>;
+    setValue: react_hook_form.UseFormSetValue<TFieldValues>;
+    trigger: react_hook_form.UseFormTrigger<TFieldValues>;
+    formState: react_hook_form.FormState<TFieldValues>;
+    resetField: react_hook_form.UseFormResetField<TFieldValues>;
+    reset: react_hook_form.UseFormReset<TFieldValues>;
+    unregister: react_hook_form.UseFormUnregister<TFieldValues>;
+    control: react_hook_form.Control<TFieldValues, any, TFieldValues>;
+    register: react_hook_form.UseFormRegister<TFieldValues>;
+    setFocus: react_hook_form.UseFormSetFocus<TFieldValues>;
+    subscribe: react_hook_form.UseFormSubscribe<TFieldValues>;
+};
+type SmartFormReturn<TFieldValues extends FieldValues = FieldValues> = ReturnType<typeof useSmartForm<TFieldValues>>;
+
+/**
+ * Form field component props
+ */
+interface FormFieldProps<TFieldValues extends FieldValues = FieldValues> {
+    name: Path<TFieldValues>;
+    label: string;
+    type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url';
+    placeholder?: string;
+    required?: boolean;
+    helpText?: string;
+    disabled?: boolean;
+    className?: string;
+    control: UseFormReturn<TFieldValues>['control'];
+    render?: (field: {
+        value: unknown;
+        onChange: (...event: unknown[]) => void;
+        onBlur: () => void;
+        name: string;
+    }) => React.ReactElement;
+}
+/**
+ * Select field option
+ */
+interface SelectOption {
+    label: string;
+    value: string | number;
+    disabled?: boolean;
+}
+/**
+ * Select field component props
+ */
+interface FormSelectProps<TFieldValues extends FieldValues = FieldValues> extends Omit<FormFieldProps<TFieldValues>, 'type' | 'placeholder'> {
+    options: SelectOption[];
+    placeholder?: string;
+}
+/**
+ * Checkbox field component props
+ */
+interface FormCheckboxProps<TFieldValues extends FieldValues = FieldValues> extends Omit<FormFieldProps<TFieldValues>, 'type' | 'placeholder'> {
+    description?: string;
+}
+
+/**
+ * Smart Form Field component with automatic error handling
+ *
+ * @example
+ * ```tsx
+ * <FormField
+ *   name="email"
+ *   label="Email"
+ *   type="email"
+ *   required
+ *   control={form.control}
+ *   placeholder="Enter your email"
+ * />
+ * ```
+ */
+declare function FormField<TFieldValues extends FieldValues = FieldValues>({ name, label, type, placeholder, required, helpText, disabled, className, control, render, }: FormFieldProps<TFieldValues>): react_jsx_runtime.JSX.Element;
+
+/**
+ * Smart Form Select component
+ *
+ * @example
+ * ```tsx
+ * <FormSelect
+ *   name="country"
+ *   label="Country"
+ *   required
+ *   control={form.control}
+ *   options={[
+ *     { value: 'us', label: 'United States' },
+ *     { value: 'uk', label: 'United Kingdom' },
+ *   ]}
+ * />
+ * ```
+ */
+declare function FormSelect<TFieldValues extends FieldValues = FieldValues>({ name, label, options, placeholder, required, helpText, disabled, className, control, }: FormSelectProps<TFieldValues>): react_jsx_runtime.JSX.Element;
+
+/**
+ * Smart Form Checkbox component
+ *
+ * @example
+ * ```tsx
+ * <FormCheckbox
+ *   name="acceptTerms"
+ *   label="I accept the terms and conditions"
+ *   required
+ *   control={form.control}
+ *   description="You must accept the terms to continue"
+ * />
+ * ```
+ */
+declare function FormCheckbox<TFieldValues extends FieldValues = FieldValues>({ name, label, description, required, helpText, disabled, className, control, }: FormCheckboxProps<TFieldValues>): react_jsx_runtime.JSX.Element;
+
+interface FormTextareaProps<TFieldValues extends FieldValues = FieldValues> {
+    name: Path<TFieldValues>;
+    label: string;
+    placeholder?: string;
+    required?: boolean;
+    helpText?: string;
+    disabled?: boolean;
+    className?: string;
+    control: Control<TFieldValues>;
+    rows?: number;
+    maxLength?: number;
+    showCharacterCount?: boolean;
+    resize?: 'none' | 'vertical' | 'horizontal' | 'both';
+}
+/**
+ * Smart Form Textarea component with character counter
+ *
+ * @example
+ * ```tsx
+ * <FormTextarea
+ *   name="description"
+ *   label="Description"
+ *   control={form.control}
+ *   rows={4}
+ *   maxLength={500}
+ *   showCharacterCount
+ * />
+ * ```
+ */
+declare function FormTextarea<TFieldValues extends FieldValues = FieldValues>({ name, label, placeholder, required, helpText, disabled, className, control, rows, maxLength, showCharacterCount, resize, }: FormTextareaProps<TFieldValues>): react_jsx_runtime.JSX.Element;
+
+interface FormFileUploadProps<TFieldValues extends FieldValues = FieldValues> {
+    name: Path<TFieldValues>;
+    label: string;
+    required?: boolean;
+    helpText?: string;
+    disabled?: boolean;
+    className?: string;
+    control: Control<TFieldValues>;
+    accept?: string;
+    multiple?: boolean;
+    maxSize?: number;
+    showPreview?: boolean;
+    onFileChange?: (files: FileList | null) => void;
+}
+/**
+ * Smart Form File Upload component with preview
+ *
+ * @example
+ * ```tsx
+ * <FormFileUpload
+ *   name="avatar"
+ *   label="Profile Picture"
+ *   control={form.control}
+ *   accept="image/*"
+ *   maxSize={5 * 1024 * 1024} // 5MB
+ *   showPreview
+ * />
+ * ```
+ */
+declare function FormFileUpload<TFieldValues extends FieldValues = FieldValues>({ name, label, required, helpText, disabled, className, control, accept, multiple, maxSize, showPreview, onFileChange, }: FormFileUploadProps<TFieldValues>): react_jsx_runtime.JSX.Element;
+
+interface FormDatePickerProps<TFieldValues extends FieldValues = FieldValues> {
+    name: Path<TFieldValues>;
+    label: string;
+    placeholder?: string;
+    required?: boolean;
+    helpText?: string;
+    disabled?: boolean;
+    className?: string;
+    control: Control<TFieldValues>;
+    min?: string;
+    max?: string;
+    mode?: 'single' | 'range';
+}
+/**
+ * Smart Form Date Picker component
+ *
+ * @example
+ * ```tsx
+ * <FormDatePicker
+ *   name="birthDate"
+ *   label="Birth Date"
+ *   control={form.control}
+ *   max={new Date().toISOString().split('T')[0]}
+ * />
+ * ```
+ */
+declare function FormDatePicker<TFieldValues extends FieldValues = FieldValues>({ name, label, placeholder, required, helpText, disabled, className, control, min, max, mode, }: FormDatePickerProps<TFieldValues>): react_jsx_runtime.JSX.Element;
+
+interface MultiSelectOption {
+    value: string | number;
+    label: string;
+    disabled?: boolean;
+}
+interface FormMultiSelectProps<TFieldValues extends FieldValues = FieldValues> {
+    name: Path<TFieldValues>;
+    label: string;
+    options: MultiSelectOption[];
+    required?: boolean;
+    helpText?: string;
+    disabled?: boolean;
+    className?: string;
+    control: Control<TFieldValues>;
+    layout?: 'vertical' | 'horizontal' | 'grid';
+    maxSelection?: number;
+}
+/**
+ * Smart Form Multi-Select component
+ *
+ * @example
+ * ```tsx
+ * <FormMultiSelect
+ *   name="interests"
+ *   label="Interests"
+ *   control={form.control}
+ *   options={[
+ *     { value: 'sports', label: 'Sports' },
+ *     { value: 'music', label: 'Music' },
+ *     { value: 'tech', label: 'Technology' },
+ *   ]}
+ *   layout="grid"
+ * />
+ * ```
+ */
+declare function FormMultiSelect<TFieldValues extends FieldValues = FieldValues>({ name, label, options, required, helpText, disabled, className, control, layout, maxSelection, }: FormMultiSelectProps<TFieldValues>): react_jsx_runtime.JSX.Element;
+
+interface FormLayoutProps extends React$1.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Number of columns for the form layout
+     * @default 1
+     */
+    columns?: 1 | 2 | 3 | 4;
+    /**
+     * Spacing between form fields
+     * @default "md"
+     */
+    spacing?: 'sm' | 'md' | 'lg';
+    /**
+     * Make the layout responsive (mobile: 1 col, tablet: 2 cols, desktop: specified cols)
+     * @default true
+     */
+    responsive?: boolean;
+}
+/**
+ * FormLayout - Ready-to-use form grid layout
+ *
+ * @example
+ * ```tsx
+ * <FormLayout columns={2}>
+ *   <FormField name="firstName" label="First Name" control={form.control} />
+ *   <FormField name="lastName" label="Last Name" control={form.control} />
+ * </FormLayout>
+ * ```
+ */
+declare function FormLayout({ columns, spacing, responsive, className, children, ...props }: FormLayoutProps): react_jsx_runtime.JSX.Element;
+declare namespace FormLayout {
+    var displayName: string;
+}
+
+interface FormSectionProps extends React$1.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Section title
+     */
+    title?: string;
+    /**
+     * Section description
+     */
+    description?: string;
+    /**
+     * Number of columns for this section
+     * @default 1
+     */
+    columns?: 1 | 2 | 3 | 4;
+    /**
+     * Spacing between fields
+     * @default "md"
+     */
+    spacing?: 'sm' | 'md' | 'lg';
+}
+/**
+ * FormSection - Section with title and grid layout
+ *
+ * @example
+ * ```tsx
+ * <FormSection title="Personal Info" description="Enter your details" columns={2}>
+ *   <FormField name="name" label="Name" control={form.control} />
+ *   <FormField name="email" label="Email" control={form.control} />
+ * </FormSection>
+ * ```
+ */
+declare function FormSection({ title, description, columns, spacing, className, children, ...props }: FormSectionProps): react_jsx_runtime.JSX.Element;
+declare namespace FormSection {
+    var displayName: string;
+}
+
+interface FormGridProps extends React$1.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Spacing between items
+     * @default "md"
+     */
+    spacing?: 'sm' | 'md' | 'lg';
+}
+interface FormGridItemProps extends React$1.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Column span for the item
+     * @default 1
+     */
+    colSpan?: 1 | 2 | 3 | 4 | 'full';
+}
+/**
+ * FormGrid - Advanced grid layout with col-span support
+ *
+ * @example
+ * ```tsx
+ * <FormGrid>
+ *   <FormGridItem>
+ *     <FormField name="firstName" label="First Name" control={form.control} />
+ *   </FormGridItem>
+ *   <FormGridItem>
+ *     <FormField name="lastName" label="Last Name" control={form.control} />
+ *   </FormGridItem>
+ *   <FormGridItem colSpan="full">
+ *     <FormField name="bio" label="Bio" control={form.control} />
+ *   </FormGridItem>
+ * </FormGrid>
+ * ```
+ */
+declare function FormGrid({ spacing, className, children, ...props }: FormGridProps): react_jsx_runtime.JSX.Element;
+declare namespace FormGrid {
+    var displayName: string;
+}
+/**
+ * FormGridItem - Item within FormGrid with custom column span
+ */
+declare function FormGridItem({ colSpan, className, children, ...props }: FormGridItemProps): react_jsx_runtime.JSX.Element;
+declare namespace FormGridItem {
+    var displayName: string;
+}
+
+interface FormWizardStep {
+    title: string;
+    description?: string;
+    content: React$1.ReactNode;
+    onValidate?: () => boolean | Promise<boolean>;
+}
+interface FormWizardProps {
+    steps: FormWizardStep[];
+    onComplete: () => void | Promise<void>;
+    onCancel?: () => void;
+    className?: string;
+    showStepNumbers?: boolean;
+}
+/**
+ * Form Wizard component for multi-step forms
+ *
+ * @example
+ * ```tsx
+ * <FormWizard
+ *   steps={[
+ *     {
+ *       title: 'Personal Info',
+ *       content: <PersonalInfoForm />,
+ *       onValidate: () => form.trigger(['name', 'email']),
+ *     },
+ *     {
+ *       title: 'Address',
+ *       content: <AddressForm />,
+ *     },
+ *   ]}
+ *   onComplete={() => form.handleSubmit(onSubmit)()}
+ * />
+ * ```
+ */
+declare function FormWizard({ steps, onComplete, onCancel, className, showStepNumbers, }: FormWizardProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Field array options
+ */
+interface FieldArrayOptions<TFieldValues extends FieldValues = FieldValues> {
+    /**
+     * Field array name
+     */
+    name: ArrayPath<TFieldValues>;
+    /**
+     * Form control instance
+     */
+    control: UseFormReturn<TFieldValues>['control'];
+    /**
+     * Default value for new items
+     */
+    defaultValue?: unknown;
+}
+/**
+ * Wrapper around React Hook Form's useFieldArray with smart defaults
+ *
+ * @example
+ * ```tsx
+ * const { fields, append, remove } = useSmartFieldArray({
+ *   name: 'items',
+ *   control: form.control,
+ *   defaultValue: { name: '', quantity: 0 }
+ * })
+ * ```
+ */
+declare function useSmartFieldArray<TFieldValues extends FieldValues = FieldValues>({ name, control, defaultValue, }: FieldArrayOptions<TFieldValues>): {
+    append: (value?: unknown) => void;
+    swap: react_hook_form.UseFieldArraySwap;
+    move: react_hook_form.UseFieldArrayMove;
+    prepend: react_hook_form.UseFieldArrayPrepend<TFieldValues, ArrayPath<TFieldValues>>;
+    remove: react_hook_form.UseFieldArrayRemove;
+    insert: react_hook_form.UseFieldArrayInsert<TFieldValues, ArrayPath<TFieldValues>>;
+    update: react_hook_form.UseFieldArrayUpdate<TFieldValues, ArrayPath<TFieldValues>>;
+    replace: react_hook_form.UseFieldArrayReplace<TFieldValues, ArrayPath<TFieldValues>>;
+    fields: react_hook_form.FieldArrayWithId<TFieldValues, ArrayPath<TFieldValues>, "id">[];
+};
+
+/**
+ * Common Validation Schemas
+ *
+ * Reusable Zod schemas for common validation patterns.
+ */
+
+/**
+ * Email validation schema
+ */
+declare const emailSchema: z.ZodString;
+/**
+ * Password validation schema
+ * At least 8 characters, 1 uppercase, 1 lowercase, 1 number
+ */
+declare const passwordSchema: z.ZodString;
+/**
+ * Strong password validation schema
+ * At least 12 characters, 1 uppercase, 1 lowercase, 1 number, 1 special character
+ */
+declare const strongPasswordSchema: z.ZodString;
+/**
+ * Phone number validation schema (international format)
+ */
+declare const phoneSchema: z.ZodString;
+/**
+ * URL validation schema
+ */
+declare const urlSchema: z.ZodString;
+/**
+ * Username validation schema
+ * 3-20 characters, alphanumeric and underscores only
+ */
+declare const usernameSchema: z.ZodString;
+/**
+ * Slug validation schema
+ * Lowercase letters, numbers, and hyphens only
+ */
+declare const slugSchema: z.ZodString;
+/**
+ * Positive number schema
+ */
+declare const positiveNumberSchema: z.ZodNumber;
+/**
+ * Positive integer schema
+ */
+declare const positiveIntegerSchema: z.ZodNumber;
+/**
+ * Price schema (two decimal places)
+ */
+declare const priceSchema: z.ZodNumber;
+/**
+ * Percentage schema (0-100)
+ */
+declare const percentageSchema: z.ZodNumber;
+/**
+ * Date string schema (ISO format)
+ */
+declare const dateStringSchema: z.ZodString;
+/**
+ * Future date schema
+ */
+declare const futureDateSchema: z.ZodEffects<z.ZodString, string, string>;
+/**
+ * Past date schema
+ */
+declare const pastDateSchema: z.ZodEffects<z.ZodString, string, string>;
+/**
+ * File size validation helper
+ */
+declare const createFileSizeSchema: (maxSizeInBytes: number, message?: string) => z.ZodEffects<z.ZodType<File, z.ZodTypeDef, File>, File, File>;
+/**
+ * File type validation helper
+ */
+declare const createFileTypeSchema: (allowedTypes: string[], message?: string) => z.ZodEffects<z.ZodType<File, z.ZodTypeDef, File>, File, File>;
+/**
+ * Image file schema (common image types, max 5MB)
+ */
+declare const imageFileSchema: z.ZodEffects<z.ZodEffects<z.ZodType<File, z.ZodTypeDef, File>, File, File>, File, File>;
+/**
+ * Confirm password schema helper
+ */
+declare const createConfirmPasswordSchema: (passwordField: string) => z.ZodEffects<z.ZodObject<{
+    [x: string]: z.ZodString;
+    confirmPassword: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    [x: string]: string;
+    confirmPassword?: unknown;
+}, {
+    [x: string]: string;
+    confirmPassword?: unknown;
+}>, {
+    [x: string]: string;
+    confirmPassword?: unknown;
+}, {
+    [x: string]: string;
+    confirmPassword?: unknown;
+}>;
+/**
+ * Optional email schema (can be empty or valid email)
+ */
+declare const optionalEmailSchema: z.ZodUnion<[z.ZodString, z.ZodString]>;
+/**
+ * Optional URL schema
+ */
+declare const optionalUrlSchema: z.ZodUnion<[z.ZodString, z.ZodString]>;
+
+/**
+ * Validation Helper Utilities
+ *
+ * Helper functions for common validation patterns.
+ */
+
+/**
+ * Get error message from field errors
+ */
+declare function getErrorMessage(errors: FieldErrors, fieldName: string): string | undefined;
+/**
+ * Check if field has error
+ */
+declare function hasError(errors: FieldErrors, fieldName: string): boolean;
+/**
+ * Get all error messages as array
+ */
+declare function getAllErrors(errors: FieldErrors): string[];
+/**
+ * Create a conditional schema based on another field
+ *
+ * @example
+ * ```ts
+ * const schema = z.object({
+ *   type: z.enum(['individual', 'company']),
+ *   companyName: conditionalSchema(
+ *     'type',
+ *     (type) => type === 'company',
+ *     z.string().min(1, 'Company name is required')
+ *   ),
+ * })
+ * ```
+ */
+declare function conditionalSchema<T extends ZodTypeAny>(_dependentField: string, _condition: (value: any) => boolean, schema: T): ZodTypeAny;
+/**
+ * Create min/max length message
+ */
+declare function lengthMessage(field: string, min?: number, max?: number): string;
+/**
+ * Create required field message
+ */
+declare function requiredMessage(field: string): string;
+/**
+ * Create invalid format message
+ */
+declare function invalidFormatMessage(field: string): string;
+/**
+ * Validate credit card using Luhn algorithm
+ */
+declare function validateCreditCard(cardNumber: string): boolean;
+/**
+ * Validate IBAN (International Bank Account Number)
+ */
+declare function validateIBAN(iban: string): boolean;
+/**
+ * Validate strong password requirements
+ */
+declare function validatePasswordStrength(password: string): {
+    isStrong: boolean;
+    missingRequirements: string[];
+};
+/**
+ * Sanitize string input (remove HTML, trim, normalize whitespace)
+ */
+declare function sanitizeString(input: string): string;
+/**
+ * Validate file extension
+ */
+declare function validateFileExtension(filename: string, allowedExtensions: string[]): boolean;
+/**
+ * Format validation error for display
+ */
+declare function formatValidationError(error: z.ZodError): Record<string, string>;
+
+export { type FieldArrayOptions, FormCheckbox, type FormCheckboxProps, FormDatePicker, type FormDatePickerProps, FormField, type FormFieldProps, FormFileUpload, type FormFileUploadProps, FormGrid, FormGridItem, type FormGridItemProps, type FormGridProps, FormLayout, type FormLayoutProps, FormMultiSelect, type FormMultiSelectProps, FormSection, type FormSectionProps, FormSelect, type FormSelectProps, FormTextarea, type FormTextareaProps, FormWizard, type FormWizardProps, type FormWizardStep, type MultiSelectOption, type SelectOption, type SmartFormOptions, type SmartFormReturn, conditionalSchema, createConfirmPasswordSchema, createFileSizeSchema, createFileTypeSchema, dateStringSchema, emailSchema, formatValidationError, futureDateSchema, getAllErrors, getErrorMessage, hasError, imageFileSchema, invalidFormatMessage, lengthMessage, optionalEmailSchema, optionalUrlSchema, passwordSchema, pastDateSchema, percentageSchema, phoneSchema, positiveIntegerSchema, positiveNumberSchema, priceSchema, requiredMessage, sanitizeString, slugSchema, strongPasswordSchema, urlSchema, useSmartFieldArray, useSmartForm, usernameSchema, validateCreditCard, validateFileExtension, validateIBAN, validatePasswordStrength };