@akad/form-builder 1.0.0

package/components/FormBuilder/FormBuilder.config.d.ts

@@ -0,0 +1,333 @@
+import { JSONSchema7 } from 'json-schema';
+export declare const ValidationMode: {
+    readonly OnChange: "onChange";
+    readonly OnBlur: "onBlur";
+    readonly OnSubmit: "onSubmit";
+    readonly Eager: "eager";
+};
+export type ValidationMode = (typeof ValidationMode)[keyof typeof ValidationMode];
+export declare const ComponentType: {
+    readonly Input: "Input";
+    readonly Select: "Select";
+    readonly TextArea: "TextArea";
+    readonly Checkbox: "Checkbox";
+    readonly Button: "Button";
+    readonly EditableSelect: "EditableSelect";
+    readonly CoverageList: "CoverageList";
+    readonly RadioGroup: "RadioGroup";
+    readonly MultiSelect: "MultiSelect";
+    readonly CheckboxGroup: "CheckboxGroup";
+    readonly DatePicker: "DatePicker";
+    readonly FileUpload: "FileUpload";
+    readonly ArrayInput: "ArrayInput";
+    readonly ObjectInput: "ObjectInput";
+};
+export type ComponentType = (typeof ComponentType)[keyof typeof ComponentType];
+export declare const FieldType: {
+    readonly String: "string";
+    readonly Number: "number";
+    readonly Integer: "integer";
+    readonly Boolean: "boolean";
+    readonly Array: "array";
+    readonly Object: "object";
+};
+export type FieldType = (typeof FieldType)[keyof typeof FieldType];
+export declare const LayoutType: {
+    readonly Grid: "grid";
+    readonly Flex: "flex";
+    readonly Custom: "custom";
+};
+export type LayoutType = (typeof LayoutType)[keyof typeof LayoutType];
+export interface FieldOption {
+    value: string | number | boolean;
+    label: string;
+    description?: string;
+    disabled?: boolean;
+    icon?: string;
+    group?: string;
+    data?: Record<string, unknown>;
+}
+export interface ValidationRules {
+    type?: FieldType;
+    required?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    multipleOf?: number;
+    pattern?: string;
+    format?: string;
+    enum?: (string | number | boolean)[];
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    customValidators?: string[];
+    crossField?: CrossFieldValidationRule[];
+}
+export interface CrossFieldValidationRule {
+    field: string;
+    affects: string[];
+    rule: string;
+}
+export interface GridConfig {
+    col?: number;
+    offset?: number;
+    row?: number;
+    rowSpan?: number;
+    colSpan?: number;
+    sm?: Partial<GridConfig>;
+    md?: Partial<GridConfig>;
+    lg?: Partial<GridConfig>;
+    xl?: Partial<GridConfig>;
+    xxl?: Partial<GridConfig>;
+}
+export interface FlexConfig {
+    grow?: number;
+    shrink?: number;
+    basis?: string;
+    align?: 'start' | 'center' | 'end' | 'stretch';
+}
+export interface ConditionalConfig {
+    field: string;
+    operator: ConditionalOperator;
+    value: unknown;
+    and?: ConditionalConfig[];
+    or?: ConditionalConfig[];
+    not?: ConditionalConfig;
+}
+export type ConditionalOperator = '==' | '!=' | '>' | '<' | '>=' | '<=' | 'in' | 'not_in' | 'exists' | 'empty' | 'contains' | 'starts_with' | 'ends_with';
+export interface FieldConfig {
+    name: string;
+    type: FieldType;
+    component: ComponentType;
+    label?: string;
+    placeholder?: string;
+    help?: string;
+    options?: FieldOption[];
+    required: boolean;
+    validation: ValidationRules;
+    layout: {
+        grid?: GridConfig;
+        flex?: FlexConfig;
+        spacing?: string;
+    };
+    props: Record<string, unknown>;
+    conditional?: ConditionalConfig;
+    order?: number;
+    disabled?: boolean;
+    hidden?: boolean;
+    nullable?: boolean;
+}
+export interface FieldError {
+    message: string;
+    type: string;
+    value: unknown;
+    severity?: 'error' | 'warning' | 'info';
+    schemaPath?: string;
+    data?: Record<string, unknown>;
+}
+export interface ValidationResult {
+    isValid: boolean;
+    errors: Record<string, FieldError>;
+    validFields: string[];
+    invalidFields: string[];
+    warnings?: Record<string, FieldError>;
+}
+export interface FieldValidationResult {
+    isValid: boolean;
+    error?: FieldError;
+}
+export type ValidatorFunction = (value: unknown, data?: Record<string, unknown>) => ValidationResult | Promise<ValidationResult>;
+export interface ComponentRegistry {
+    [componentName: string]: React.ComponentType<ComponentProps>;
+}
+export interface ComponentProps {
+    name: string;
+    value: unknown;
+    onChange: (value: unknown) => void;
+    onBlur?: () => void;
+    onFocus?: () => void;
+    error?: string | FieldError;
+    disabled?: boolean;
+    readonly?: boolean;
+    required?: boolean;
+    label?: string;
+    placeholder?: string;
+    help?: string;
+    options?: FieldOption[];
+    [key: string]: unknown;
+}
+export interface UseFormStateConfig {
+    initialData?: Record<string, unknown>;
+    deepEqual?: boolean;
+}
+export interface UseFormStateReturn {
+    formData: Record<string, unknown>;
+    setFormData: (data: Record<string, unknown>) => void;
+    updateFormData: (data: Partial<Record<string, unknown>>) => void;
+    setField: (fieldName: string, value: unknown) => void;
+    clearForm: () => void;
+    resetForm: () => void;
+    isDirty: boolean;
+    touched: Record<string, boolean>;
+    setTouched: (fieldName: string, touched?: boolean) => void;
+}
+export interface UseFormValidationConfig {
+    schema: JSONSchema7;
+    mode?: ValidationMode;
+    customValidators?: Record<string, ValidatorFunction>;
+    errorMessages?: Record<string, string>;
+    debounce?: number;
+}
+export interface UseFormValidationReturn {
+    validateForm: (data: Record<string, unknown>) => Promise<ValidationResult>;
+    validateFields: (data: Record<string, unknown>, fieldNames: string[]) => ValidationResult;
+    validateField: (fieldName: string, value: unknown, fullFormData?: Record<string, unknown>) => FieldValidationResult;
+    validateSilent: (data: Record<string, unknown>) => boolean;
+    isValid: boolean;
+    errors: Record<string, FieldError>;
+    isValidating: boolean;
+    clearErrors: () => void;
+    clearFieldError: (fieldName: string) => void;
+}
+export interface UseFormParserConfig {
+    schema: JSONSchema7;
+}
+export interface UseFormParserReturn {
+    parseToObject: (data: Record<string, unknown>) => Record<string, unknown>;
+    parseField: (fieldName: string, value: unknown) => unknown;
+    getFieldType: (fieldName: string) => string;
+}
+export interface UseFormConfig {
+    schema: JSONSchema7;
+    initialData?: Record<string, unknown>;
+    mode?: ValidationMode;
+    customValidators?: Record<string, ValidatorFunction>;
+    errorMessages?: Record<string, string>;
+    validationDebounce?: number;
+}
+export interface UseFormReturn {
+    data: Record<string, unknown>;
+    setData: (data: Record<string, unknown>) => void;
+    setField: (fieldName: string, value: unknown) => void;
+    getFieldErrorMessage: (field: FieldConfig, state: UseFormReturn) => string | undefined;
+    clear: () => void;
+    reset: () => void;
+    isDirty: boolean;
+    touched: Record<string, boolean>;
+    validate: () => Promise<ValidationResult>;
+    validateFields: (fieldNames: string[]) => ValidationResult;
+    validateField: (fieldName: string, fullFormData?: Record<string, unknown>) => FieldValidationResult;
+    validateSilent: (data: Record<string, unknown>) => boolean;
+    clearErrors: () => void;
+    isValid: boolean;
+    errors: Record<string, FieldError>;
+    isValidating: boolean;
+    parse: () => Record<string, unknown>;
+    onBlur: (fieldName: string) => void;
+}
+export interface UISchema {
+    [stepId: string]: UISchemaStep;
+}
+export interface UISchemaStep {
+    'ui:layout'?: LayoutType;
+    'ui:columns'?: number;
+    'ui:gap'?: string;
+    'ui:spacing'?: string;
+    'ui:className'?: string;
+    'ui:style'?: React.CSSProperties;
+    'ui:responsive'?: ResponsiveConfig;
+    [fieldName: string]: UISchemaField | unknown;
+}
+export interface UISchemaField {
+    'ui:component'?: ComponentType;
+    'ui:grid'?: GridConfig;
+    'ui:flex'?: FlexConfig;
+    'ui:spacing'?: string;
+    'ui:props'?: Record<string, unknown>;
+    'ui:options'?: Array<{
+        label: string;
+        value: string | number | boolean;
+        detail?: string;
+        disabled?: boolean;
+    }>;
+    'ui:show'?: ConditionalConfig;
+    'ui:className'?: string;
+    'ui:style'?: React.CSSProperties;
+    'ui:order'?: number;
+}
+export interface ResponsiveConfig {
+    sm?: Partial<UISchemaStep>;
+    md?: Partial<UISchemaStep>;
+    lg?: Partial<UISchemaStep>;
+    xl?: Partial<UISchemaStep>;
+    xxl?: Partial<UISchemaStep>;
+}
+export interface FormBuilderProps {
+    schema: JSONSchema7;
+    uiSchema: UISchema;
+    form: UseFormReturn;
+    components?: ComponentRegistry;
+    className?: string;
+    style?: React.CSSProperties;
+    testId?: string;
+    disabled?: boolean;
+    readonly?: boolean;
+}
+export interface FieldRendererProps {
+    field: FieldConfig;
+    form: UseFormReturn;
+    uiConfig: UISchemaField;
+    components?: ComponentRegistry;
+    className?: string;
+    disabled?: boolean;
+    readonly?: boolean;
+}
+export interface ComponentDetectionRule {
+    default: ComponentType;
+    props?: Record<string, unknown>;
+    conditions?: ComponentCondition[];
+}
+export interface ComponentCondition {
+    when: (schema: JSONSchema7) => boolean;
+    use: ComponentType;
+    props?: Record<string, unknown>;
+}
+export interface FormBuilderConfigType {
+    name: string;
+    class: string;
+    props: {
+        schema: {
+            type: ObjectConstructor;
+            required: boolean;
+        };
+        uiSchema: {
+            type: ObjectConstructor;
+            required: boolean;
+        };
+        form: {
+            type: ObjectConstructor;
+            required: boolean;
+        };
+        components: {
+            type: ObjectConstructor;
+            required: boolean;
+            default: ComponentRegistry;
+        };
+        mode: {
+            type: StringConstructor;
+            default: ValidationMode;
+            options: ValidationMode[];
+        };
+        disabled: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        readonly: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    };
+}
+declare const FormBuilderConfig: FormBuilderConfigType;
+export default FormBuilderConfig;

package/components/FormBuilder/FormBuilder.d.ts

@@ -0,0 +1,31 @@
+import { default as React } from 'react';
+import { FormBuilderProps } from './FormBuilder.config';
+/**
+ * Main FormBuilder component
+ * @description Transforms JSON Schema and UI Schema into fully rendered form with validation, layout, and component integration
+ * @param schema JSONSchema7 defining field types, validation rules, and data structure
+ * @param uiSchema UI Schema defining layout, components, and presentation
+ * @param form Form state object from useForm hook containing data and validation
+ * @param components Optional custom component registry to override built-in components
+ * @param className Optional additional CSS classes for form container
+ * @param style Optional inline styles for form container
+ * @param testId Optional test identifier for form container
+ * @param disabled Optional global disabled state for all fields
+ * @param readonly Optional global readonly state for all fields
+ * @returns React element with complete rendered form
+ * @example
+ * ```tsx
+ * const form = FormBuilder.useForm({ schema: contactSchema, mode: 'onChange' });
+ *
+ * <FormBuilder
+ *   schema={contactSchema}
+ *   uiSchema={contactUISchema}
+ *   form={form}
+ *   components={{ CustomInput: MyInput }}
+ *   className="my-form"
+ *   testId="contact-form"
+ * />
+ * ```
+ */
+export declare const FormBuilder: React.FC<FormBuilderProps>;
+export default FormBuilder;

package/components/FormBuilder/components/AddressFormGroup/AddressFormGroup.d.ts

@@ -0,0 +1,53 @@
+import { default as React } from 'react';
+import { ComponentProps } from '../../FormBuilder.config';
+/**
+ * AddressFormGroup - Native FormBuilder field group component
+ *
+ * @description Renders individual address fields that work directly with FormBuilder's
+ * field-by-field validation system. Unlike components that return objects, this renders
+ * multiple FormBuilder-compatible fields (address.postCode, address.state, etc).
+ *
+ * Key design:
+ * - Renders 7 individual fields, each validated independently
+ * - Each field uses form.setField() for native FormBuilder integration
+ * - Errors appear on the correct field automatically
+ * - No object conversion or validation hacks needed
+ * - Works in any fill order (not dependent on CEP being filled first)
+ */
+interface AddressResponse {
+    cep?: string;
+    uf?: string;
+    localidade?: string;
+    bairro?: string;
+    logradouro?: string;
+    complemento?: string;
+    erro?: boolean;
+    [key: string]: unknown;
+}
+export interface AddressFormGroupProps extends ComponentProps {
+    name: string;
+    __form?: {
+        data: Record<string, unknown>;
+        setField: (name: string, value: unknown) => void;
+        errors: Record<string, {
+            message?: string;
+        }>;
+    };
+    getAddress?: (postCode: string) => Promise<AddressResponse>;
+    title?: string;
+    labels?: {
+        postCode?: string;
+        state?: string;
+        city?: string;
+        suburb?: string;
+        street?: string;
+        number?: string;
+        complement?: string;
+    };
+    masks?: {
+        postCode?: string;
+    };
+    disabled?: boolean;
+}
+declare const AddressFormGroup: React.FC<AddressFormGroupProps>;
+export default AddressFormGroup;

package/components/FormBuilder/components/AddressFormGroup/AddressFormGroup.test.d.ts

@@ -0,0 +1 @@
+export {};

package/components/FormBuilder/components/AddressFormGroup/index.d.ts

@@ -0,0 +1,4 @@
+import { default as AddressFormGroup, AddressFormGroupProps } from './AddressFormGroup';
+export { AddressFormGroup };
+export type { AddressFormGroupProps };
+export default AddressFormGroup;

package/components/FormBuilder/components/FieldRenderer/FieldRenderer.d.ts

@@ -0,0 +1,39 @@
+import { default as React } from 'react';
+import { FieldConfig, FieldRendererProps } from '../../FormBuilder.config';
+/**
+ * Check if field should be rendered based on conditional logic
+ * @description Evaluates ui:show conditions and hidden flag to determine field visibility
+ * @param field FieldConfig containing conditional logic and hidden flag
+ * @param formData Current form data to evaluate conditions against
+ * @returns boolean indicating if field should be rendered
+ * @example
+ * ```tsx
+ * const shouldShow = shouldRenderField(
+ *   { conditional: { field: 'userType', operator: '==', value: 'business' } },
+ *   { userType: 'business' }
+ * ); // returns true
+ * ```
+ */
+export declare const shouldRenderField: (field: FieldConfig, formData: Record<string, unknown>) => boolean;
+/**
+ * Individual field renderer component
+ * @description Main component that renders form fields with component resolution and error handling
+ * @param field FieldConfig containing field configuration and layout
+ * @param form UseFormReturn with form state and validation
+ * @param components Optional custom component registry
+ * @param className Optional additional CSS classes
+ * @param disabled Optional global disabled state
+ * @param readonly Optional global readonly state
+ * @returns React element with rendered field component
+ * @example
+ * ```tsx
+ * <FieldRenderer
+ *   field={fieldConfig}
+ *   form={form}
+ *   components={{ CustomInput: MyInput }}
+ *   disabled={false}
+ * />
+ * ```
+ */
+export declare const FieldRenderer: React.FC<FieldRendererProps>;
+export default FieldRenderer;

package/components/FormBuilder/components/FieldRenderer/FieldRenderer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/components/FormBuilder/components/FieldRenderer/index.d.ts

@@ -0,0 +1,3 @@
+import { FieldRenderer, shouldRenderField } from './FieldRenderer';
+export { FieldRenderer, shouldRenderField };
+export default FieldRenderer;

package/components/FormBuilder/components/GenericWrapper/GenericWrapper.d.ts

@@ -0,0 +1,61 @@
+import { default as React } from 'react';
+import { ComponentProps, ComponentRegistry, FieldConfig, UISchemaField, UseFormReturn } from '../../FormBuilder.config';
+/**
+ * Interface for GenericWrapper props
+ * @description Props for GenericWrapper component that renders a container with nested fields
+ */
+export interface GenericWrapperProps extends ComponentProps {
+    /** The wrapper component name (e.g., 'DsCard', 'DsNotification') */
+    __wrapperComponent?: string;
+    /** Child fields configuration to render inside the wrapper */
+    children?: Record<string, FieldConfig>;
+    /** Custom component registry for child fields */
+    components?: ComponentRegistry;
+    /** Form instance for managing child fields state */
+    __form?: UseFormReturn;
+    /** JSON Schema for legacy component integration */
+    __schema?: Record<string, unknown>;
+    /** UI Schema for child fields */
+    __uiSchema?: Record<string, UISchemaField>;
+    /** Horizontal gap spacing for grid layout (Design System spacing tokens: quark, nano, xs, sm, md, lg, xl, etc.) */
+    hGapSpacing?: string;
+    /** Vertical gap spacing for grid layout (Design System spacing tokens: quark, nano, xs, sm, md, lg, xl, etc.) */
+    vGapSpacing?: string;
+}
+/**
+ * GenericWrapper Component
+ * @description Generic wrapper that can render any container component with nested FormBuilder fields as children
+ *
+ * @example
+ * ```tsx
+ * // In UI Schema:
+ * riskInfo: {
+ *   'ui:component': 'GenericWrapper',
+ *   'ui:grid': { col: 12 },
+ *   'ui:props': {
+ *     wrapperComponent: 'DsCard',
+ *     elevation: 2,
+ *     children: {
+ *       effectiveDate: {
+ *         name: 'effectiveDate',
+ *         component: 'Input',
+ *         type: 'string',
+ *         label: 'Data de vigência',
+ *         layout: { grid: { col: 6 } },
+ *         // ... other FieldConfig properties
+ *       },
+ *       retroactivity: {
+ *         name: 'retroactivity',
+ *         component: 'Select',
+ *         type: 'string',
+ *         label: 'Retroatividade',
+ *         layout: { grid: { col: 6 } },
+ *         // ... other FieldConfig properties
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare const GenericWrapper: React.FC<GenericWrapperProps>;
+export default GenericWrapper;

package/components/FormBuilder/components/GenericWrapper/GenericWrapper.test.d.ts

@@ -0,0 +1 @@
+export {};

package/components/FormBuilder/components/GenericWrapper/index.d.ts

@@ -0,0 +1,4 @@
+import { GenericWrapper, GenericWrapperProps } from './GenericWrapper';
+export { GenericWrapper };
+export type { GenericWrapperProps };
+export default GenericWrapper;

package/components/FormBuilder/components/RadioGroup/RadioGroup.d.ts

@@ -0,0 +1,67 @@
+import { default as React } from 'react';
+/**
+ * Option type for RadioGroup
+ */
+export interface RadioOption {
+    label: string | React.ReactNode;
+    value: string | number | boolean;
+    detail?: string;
+    disabled?: boolean;
+}
+/**
+ * Props for RadioGroup component
+ */
+export interface RadioGroupProps {
+    /** Field name */
+    name: string;
+    /** Array of options to render */
+    options: RadioOption[];
+    /** Current selected value */
+    value?: string | number | boolean;
+    /** Change handler */
+    onChange?: (value: string | number | boolean) => void;
+    /** Blur handler */
+    onBlur?: () => void;
+    /** Label for the radio group */
+    label?: string;
+    /** Error message */
+    error?: string;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Flex direction: 'row' (horizontal) or 'column' (vertical) */
+    direction?: 'row' | 'column';
+    /** Justify content using Design System CSS classes */
+    justifyContent?: 'start' | 'end' | 'center' | 'beetwen' | 'around' | 'evenly';
+    /** Align items using Design System CSS classes */
+    alignItems?: 'start' | 'center' | 'end' | 'stretch';
+    /** Gap between options using Design System spacing */
+    gap?: 'none' | 'quark' | 'nano' | 'xxxs' | 'xxs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl' | 'xxxl';
+    /** Test ID */
+    testId?: string;
+    /** Custom class name */
+    className?: string;
+}
+/**
+ * RadioGroup Component
+ * @description Wrapper for DsOption that renders a radio group with flexbox layout control using Design System CSS classes
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup
+ *   name="userType"
+ *   label="Tipo de Usuário"
+ *   options={[
+ *     { label: 'Pessoa Física', value: 'PF' },
+ *     { label: 'Pessoa Jurídica', value: 'PJ', detail: 'CNPJ obrigatório' },
+ *   ]}
+ *   value={formData.userType}
+ *   onChange={(value) => setFormData({ ...formData, userType: value })}
+ *   direction="row"
+ *   justifyContent="start"
+ *   alignItems="center"
+ *   gap="md"
+ * />
+ * ```
+ */
+export declare const RadioGroup: React.FC<RadioGroupProps>;
+export default RadioGroup;

package/components/FormBuilder/components/RadioGroup/RadioGroup.test.d.ts

@@ -0,0 +1 @@
+export {};

package/components/FormBuilder/components/RadioGroup/index.d.ts

@@ -0,0 +1,4 @@
+import { RadioGroup, RadioGroupProps, RadioOption } from './RadioGroup';
+export { RadioGroup };
+export type { RadioGroupProps, RadioOption };
+export default RadioGroup;

package/components/FormBuilder/hooks/useForm.d.ts

@@ -0,0 +1,30 @@
+import { UseFormConfig, UseFormReturn } from '../FormBuilder.config';
+/**
+ * Main form hook that composes state, validation, and parsing functionality
+ * @description Comprehensive form management hook combining state, validation, and parsing through composition
+ * @param config UseFormConfig with schema, initialData, validation mode, and custom validators
+ * @returns UseFormReturn with complete form interface including state, validation, and parsing methods
+ * @example
+ * ```tsx
+ * const form = useForm({
+ *   schema: contactSchema,
+ *   initialData: { name: '', email: '' },
+ *   mode: ValidationMode.OnChange,
+ *   customValidators: {
+ *     uniqueEmail: async (value) => ({ isValid: !await emailExists(value), message: 'Email already exists' })
+ *   }
+ * });
+ *
+ * // Use in component
+ * <FormBuilder schema={schema} uiSchema={uiSchema} form={form} />
+ *
+ * // Manual usage
+ * form.setField('name', 'John');
+ * const validation = await form.validate();
+ * if (validation.isValid) {
+ *   const data = form.parse(); // Type-converted data
+ * }
+ * ```
+ */
+export declare const useForm: (config: UseFormConfig) => UseFormReturn;
+export default useForm;

package/components/FormBuilder/hooks/useForm.test.d.ts

@@ -0,0 +1 @@
+export {};

package/components/FormBuilder/hooks/useFormParser.d.ts

@@ -0,0 +1,7 @@
+import { UseFormParserConfig, UseFormParserReturn } from '../FormBuilder.config';
+/**
+ * Hook for parsing and type conversion based on JSON Schema
+ * Handles data transformation from string inputs to proper types
+ */
+export declare const useFormParser: (config: UseFormParserConfig) => UseFormParserReturn;
+export default useFormParser;

package/components/FormBuilder/hooks/useFormParser.test.d.ts

@@ -0,0 +1 @@
+export {};