@mehdashti/forms 0.6.3 → 1.0.0

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 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 { ZodTypeAny, z } from 'zod';
-export { z } from 'zod';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { InputProps } from '@mehdashti/ui';
 import * as React$1 from 'react';
+import { z, ZodTypeAny } from 'zod';
+export { z } from 'zod';
 
 interface SmartFormOptions<TFieldValues extends FieldValues = FieldValues> {
-    schema: ZodTypeAny;
+    schema: any;
     onSubmit: (data: TFieldValues) => void | Promise<void>;
     onError?: (errors: Record<string, unknown>) => void;
     realtimeValidation?: boolean;
@@ -311,8 +311,172 @@ interface FormErrorSummaryProps {
      * Callback when an error link is clicked
      */
     onErrorClick?: (fieldName: string) => void;
+    /**
+     * Show error count badge
+     * @default true
+     */
+    showErrorCount?: boolean;
+    /**
+     * Auto-scroll to first error on mount
+     * @default false
+     */
+    autoScrollToFirstError?: boolean;
+}
+declare function FormErrorSummary({ title, fieldLabels, show, className, onErrorClick, showErrorCount, autoScrollToFirstError, }: FormErrorSummaryProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * FormFieldError Component
+ *
+ * Displays error icon and message for form fields.
+ */
+interface FormFieldErrorProps {
+    /**
+     * Error message to display
+     */
+    message?: string;
+    /**
+     * Show error icon
+     * @default true
+     */
+    showIcon?: boolean;
+    /**
+     * Custom className
+     */
+    className?: string;
+    /**
+     * Field ID for accessibility
+     */
+    fieldId?: string;
+}
+/**
+ * FormFieldError - Displays error icon and message
+ *
+ * @example
+ * ```tsx
+ * <FormFieldError message={errors.email?.message} fieldId="email" />
+ * ```
+ */
+declare function FormFieldError({ message, showIcon, className, fieldId, }: FormFieldErrorProps): react_jsx_runtime.JSX.Element | null;
+declare namespace FormFieldError {
+    var displayName: string;
+}
+
+/**
+ * useAutosave Hook
+ *
+ * Provides debounced autosave functionality for forms with save state indicators.
+ */
+
+type SaveStatus = "idle" | "saving" | "saved" | "error";
+interface UseAutosaveOptions<TData> {
+    /**
+     * Function to save the form data
+     */
+    onSave: (data: TData) => Promise<void>;
+    /**
+     * Debounce delay in milliseconds
+     * @default 2000
+     */
+    debounceMs?: number;
+    /**
+     * Whether autosave is enabled
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Callback when save succeeds
+     */
+    onSaveSuccess?: (data: TData) => void;
+    /**
+     * Callback when save fails
+     */
+    onSaveError?: (error: Error, data: TData) => void;
+    /**
+     * Fields to exclude from triggering autosave
+     */
+    excludeFields?: string[];
+}
+interface UseAutosaveReturn {
+    /**
+     * Current save status
+     */
+    status: SaveStatus;
+    /**
+     * Last save timestamp
+     */
+    lastSaved: Date | null;
+    /**
+     * Error from last save attempt
+     */
+    error: Error | null;
+    /**
+     * Manually trigger save
+     */
+    save: () => Promise<void>;
+    /**
+     * Reset save status
+     */
+    reset: () => void;
+}
+/**
+ * Hook for autosaving form data with debouncing
+ *
+ * @example
+ * ```tsx
+ * const form = useSmartForm({ ... });
+ * const autosave = useAutosave({
+ *   onSave: async (data) => {
+ *     await api.saveDraft(data);
+ *   },
+ *   debounceMs: 2000,
+ * });
+ *
+ * return (
+ *   <FormProvider {...form}>
+ *     <AutosaveIndicator status={autosave.status} lastSaved={autosave.lastSaved} />
+ *     <form>...</form>
+ *   </FormProvider>
+ * );
+ * ```
+ */
+declare function useAutosave<TData extends FieldValues = any>({ onSave, debounceMs, enabled, onSaveSuccess, onSaveError, excludeFields, }: UseAutosaveOptions<TData>): UseAutosaveReturn;
+
+interface AutosaveIndicatorProps {
+    /**
+     * Current save status
+     */
+    status: SaveStatus;
+    /**
+     * Last save timestamp
+     */
+    lastSaved?: Date | null;
+    /**
+     * Custom className
+     */
+    className?: string;
+    /**
+     * Show timestamp
+     * @default true
+     */
+    showTimestamp?: boolean;
+}
+/**
+ * AutosaveIndicator - Visual indicator for autosave status
+ *
+ * @example
+ * ```tsx
+ * const autosave = useAutosave({ ... });
+ *
+ * <AutosaveIndicator
+ *   status={autosave.status}
+ *   lastSaved={autosave.lastSaved}
+ * />
+ * ```
+ */
+declare function AutosaveIndicator({ status, lastSaved, className, showTimestamp, }: AutosaveIndicatorProps): react_jsx_runtime.JSX.Element | null;
+declare namespace AutosaveIndicator {
+    var displayName: string;
 }
-declare function FormErrorSummary({ title, fieldLabels, show, className, onErrorClick, }: FormErrorSummaryProps): react_jsx_runtime.JSX.Element | null;
 
 /**
  * Form field component props
@@ -587,6 +751,24 @@ interface FormSectionProps extends React$1.HTMLAttributes<HTMLDivElement> {
      * @default "md"
      */
     spacing?: 'sm' | 'md' | 'lg';
+    /**
+     * Make the section collapsible
+     * @default false
+     */
+    collapsible?: boolean;
+    /**
+     * Initial collapsed state (only works when collapsible is true)
+     * @default false
+     */
+    defaultCollapsed?: boolean;
+    /**
+     * Controlled collapsed state
+     */
+    collapsed?: boolean;
+    /**
+     * Callback when collapsed state changes
+     */
+    onCollapsedChange?: (collapsed: boolean) => void;
 }
 /**
  * FormSection - Section with title and grid layout
@@ -598,12 +780,87 @@ interface FormSectionProps extends React$1.HTMLAttributes<HTMLDivElement> {
  *   <FormField name="email" label="Email" control={form.control} />
  * </FormSection>
  * ```
+ *
+ * @example
+ * ```tsx
+ * <FormSection
+ *   title="Advanced Settings"
+ *   collapsible
+ *   defaultCollapsed
+ * >
+ *   <FormField name="apiKey" label="API Key" control={form.control} />
+ * </FormSection>
+ * ```
  */
-declare function FormSection({ title, description, columns, spacing, className, children, ...props }: FormSectionProps): react_jsx_runtime.JSX.Element;
+declare function FormSection({ title, description, columns, spacing, className, children, collapsible, defaultCollapsed, collapsed: controlledCollapsed, onCollapsedChange, ...props }: FormSectionProps): react_jsx_runtime.JSX.Element;
 declare namespace FormSection {
     var displayName: string;
 }
 
+interface FormFieldGroupProps extends React$1.HTMLAttributes<HTMLFieldSetElement> {
+    /**
+     * Group label (rendered as legend)
+     */
+    label?: string;
+    /**
+     * Group description
+     */
+    description?: string;
+    /**
+     * Number of columns for fields in this group
+     * @default 1
+     */
+    columns?: 1 | 2 | 3 | 4;
+    /**
+     * Spacing between fields
+     * @default "md"
+     */
+    spacing?: 'sm' | 'md' | 'lg';
+    /**
+     * Visual variant
+     * @default "default"
+     */
+    variant?: 'default' | 'bordered' | 'outlined';
+    /**
+     * Whether the group is disabled
+     */
+    disabled?: boolean;
+    /**
+     * Whether the group is required (shows * on label)
+     */
+    required?: boolean;
+}
+/**
+ * FormFieldGroup - Semantic grouping of related form fields
+ *
+ * @example
+ * ```tsx
+ * <FormFieldGroup label="Shipping Address" columns={2}>
+ *   <FormField name="street" label="Street" control={form.control} />
+ *   <FormField name="city" label="City" control={form.control} />
+ *   <FormField name="state" label="State" control={form.control} />
+ *   <FormField name="zip" label="ZIP Code" control={form.control} />
+ * </FormFieldGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <FormFieldGroup
+ *   label="Contact Information"
+ *   description="How can we reach you?"
+ *   variant="bordered"
+ *   required
+ * >
+ *   <FormField name="email" label="Email" control={form.control} />
+ *   <FormField name="phone" label="Phone" control={form.control} />
+ * </FormFieldGroup>
+ * ```
+ */
+declare function FormFieldGroup({ label, description, columns, spacing, variant, disabled, required, className, children, ...props }: FormFieldGroupProps): react_jsx_runtime.JSX.Element;
+declare namespace FormFieldGroup {
+    var displayName: string;
+}
+
 interface FormGridProps extends React$1.HTMLAttributes<HTMLDivElement> {
     /**
      * Spacing between items
@@ -1066,4 +1323,4 @@ declare function validateFileExtension(filename: string, allowedExtensions: stri
  */
 declare function formatValidationError(error: z.ZodError): Record<string, string>;
 
-export { type BlockerState, type FieldArrayOptions, FormCheckbox, type FormCheckboxProps, FormCheckbox$1 as FormCheckboxUI, type FormCheckboxProps$1 as FormCheckboxUIProps, FormDatePicker, type FormDatePickerProps, FormErrorSummary, type FormErrorSummaryProps, FormField, type FormFieldProps, FormFileUpload, type FormFileUploadProps, FormGrid, FormGridItem, type FormGridItemProps, type FormGridProps, FormInput, type FormInputProps, FormLayout, type FormLayoutProps, FormMultiSelect, type FormMultiSelectProps, FormRadioGroup, type FormRadioGroupProps, FormSection, type FormSectionProps, FormSelect, type FormSelectOption, type FormSelectProps, FormSelect$1 as FormSelectUI, type FormSelectProps$1 as FormSelectUIProps, FormSwitch, type FormSwitchProps, FormTagInput, type FormTagInputProps, FormTextarea, type FormTextareaProps, FormTextarea$1 as FormTextareaUI, type FormTextareaProps$1 as FormTextareaUIProps, FormWizard, type FormWizardProps, type FormWizardStep, type MultiSelectOption, type RadioOption, type SelectOption, type SmartFormOptions, type SmartFormReturn, type UseUnsavedChangesBlockerOptions, type UseUnsavedChangesOptions, 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, useUnsavedChanges, useUnsavedChangesBlocker, useUnsavedChangesBlockerReactRouter, useUnsavedChangesBlockerTanStack, usernameSchema, validateCreditCard, validateFileExtension, validateIBAN, validatePasswordStrength };
+export { AutosaveIndicator, type AutosaveIndicatorProps, type BlockerState, type FieldArrayOptions, FormCheckbox, type FormCheckboxProps, FormCheckbox$1 as FormCheckboxUI, type FormCheckboxProps$1 as FormCheckboxUIProps, FormDatePicker, type FormDatePickerProps, FormErrorSummary, type FormErrorSummaryProps, FormField, FormFieldError, type FormFieldErrorProps, FormFieldGroup, type FormFieldGroupProps, type FormFieldProps, FormFileUpload, type FormFileUploadProps, FormGrid, FormGridItem, type FormGridItemProps, type FormGridProps, FormInput, type FormInputProps, FormLayout, type FormLayoutProps, FormMultiSelect, type FormMultiSelectProps, FormRadioGroup, type FormRadioGroupProps, FormSection, type FormSectionProps, FormSelect, type FormSelectOption, type FormSelectProps, FormSelect$1 as FormSelectUI, type FormSelectProps$1 as FormSelectUIProps, FormSwitch, type FormSwitchProps, FormTagInput, type FormTagInputProps, FormTextarea, type FormTextareaProps, FormTextarea$1 as FormTextareaUI, type FormTextareaProps$1 as FormTextareaUIProps, FormWizard, type FormWizardProps, type FormWizardStep, type MultiSelectOption, type RadioOption, type SaveStatus, type SelectOption, type SmartFormOptions, type SmartFormReturn, type UseAutosaveOptions, type UseAutosaveReturn, type UseUnsavedChangesBlockerOptions, type UseUnsavedChangesOptions, 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, useAutosave, useSmartFieldArray, useSmartForm, useUnsavedChanges, useUnsavedChangesBlocker, useUnsavedChangesBlockerReactRouter, useUnsavedChangesBlockerTanStack, usernameSchema, validateCreditCard, validateFileExtension, validateIBAN, validatePasswordStrength };