@classytic/formkit 1.0.3 → 1.2.2

package/dist/index.d.cts

@@ -1,511 +0,0 @@
-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.
- * 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" | "custom" | (string & {});
-/**
- * Layout type identifier.
- */
-type LayoutType = "section" | "grid" | "default" | (string & {});
-/**
- * Variant identifier for component styling.
- */
-type Variant = "default" | "compact" | "inline" | (string & {}) | undefined;
-/**
- * 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.
-     * Return true to show the field, false to hide.
-     */
-    condition?: (formValues: TFieldValues) => boolean;
-    /** 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;
-    /** Additional field-specific props (for custom components) */
-    [key: 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 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<TFieldValues extends FieldValues = FieldValues> {
-    /** Unique section identifier */
-    id?: string;
-    /** Section title */
-    title?: string;
-    /** Section description */
-    description?: string;
-    /** Section icon */
-    icon?: 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.
-     * 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;
-}
-/**
- * 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;
-}
-/**
- * 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 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 { useForm } from 'react-hook-form';
- * import { FormGenerator } from '@classytic/formkit';
- *
- * interface FormData {
- *   firstName: string;
- *   email: string;
- * }
- *
- * function MyForm() {
- *   const { control } = useForm<FormData>();
- *
- *   const schema = {
- *     sections: [
- *       {
- *         title: "User Details",
- *         fields: [
- *           { name: "firstName", type: "text", label: "First Name" },
- *           { name: "email", type: "email", label: "Email" }
- *         ]
- *       }
- *     ]
- *   };
- *
- *   return <FormGenerator schema={schema} control={control} />;
- * }
- * ```
- */
-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
- *
- * 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>;
-
-/**
- * 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;
-
-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 };