@anri1214/dynamic-forms-mui 0.1.7

package/dist/index.d.ts

@@ -0,0 +1,554 @@
+import { Component } from 'react';
+import { ComponentType } from 'react';
+import { JSX } from 'react/jsx-runtime';
+import { JSXElementConstructor } from 'react';
+import { ReactElement } from 'react';
+import { ReactNode } from 'react';
+import { ReactPortal } from 'react';
+import { SxProps } from '@mui/material';
+import { TextFieldProps } from '@mui/material/TextField';
+import { Theme } from '@mui/material';
+import { z } from 'zod';
+import { ZodType } from 'zod';
+
+export declare interface AndCondition {
+    and: Condition[];
+}
+
+export declare interface ApiClient {
+    get<T>(url: string, config?: RequestConfig): Promise<T>;
+}
+
+/**
+ * Checks if all dependencies have valid values
+ */
+export declare function areDependenciesFilled(dependencies: string[], values: Record<string, unknown>): boolean;
+
+export declare interface AsyncValidationConfig {
+    apiUrl: string;
+    queryParams?: QueryParam[];
+    debounce?: number;
+    message: string;
+}
+
+export declare interface AutocompleteFieldConfig extends BaseFieldConfig {
+    type: 'autocomplete';
+    options?: Option_2[];
+    optionsSource?: OptionsSource;
+    initialOptions?: Option_2[];
+}
+
+export declare interface BaseFieldConfig {
+    type: FieldType;
+    label: string;
+    placeholder?: string;
+    helperText?: string;
+    defaultValue?: unknown;
+    disabled?: boolean;
+    showIf?: Condition;
+    validation?: ValidationRules;
+}
+
+/**
+ * Builds URL for options API call
+ */
+export declare function buildOptionsUrl(source: OptionsSource, values: Record<string, unknown>, inputValue?: string): string;
+
+/**
+ * Builds a Zod schema from FormSchema
+ * Note: requiredIf and matchField are handled via refine
+ */
+export declare function buildZodSchema(schema: FormSchema): z.ZodObject<Record<string, ZodType>>;
+
+export declare interface CheckboxFieldConfig extends BaseFieldConfig {
+    type: 'checkbox' | 'switch';
+    defaultValue?: boolean;
+}
+
+export declare type ComponentSize = 'small' | 'medium';
+
+export declare type Condition = SimpleCondition | AndCondition | OrCondition;
+
+export declare type ConditionOperator = 'equals' | 'notEquals' | 'in' | 'notIn' | 'isEmpty' | 'isNotEmpty' | 'gt' | 'gte' | 'lt' | 'lte';
+
+export declare interface DateFieldConfig extends BaseFieldConfig {
+    type: 'date' | 'dateRange';
+    includeTime?: boolean;
+    minDate?: string;
+    maxDate?: string;
+    format?: string;
+}
+
+export declare interface DFAutocompleteProps {
+    multiple?: boolean;
+    options: Option_2[];
+    value?: Option_2 | Option_2[] | null;
+    onChange?: (event: unknown, newValue: unknown) => void;
+    isOptionEqualToValue?: (option: Option_2, value: Option_2) => boolean;
+    label?: string;
+    required?: boolean;
+    placeholder?: string;
+    error?: boolean;
+    helperText?: string;
+    disabled?: boolean;
+    loading?: boolean;
+    name?: string;
+    onBlur?: () => void;
+    size?: ComponentSize;
+    ref?: React.Ref<unknown>;
+    inputValue?: string;
+    onInputChange?: (event: unknown, value: string, reason: string) => void;
+    filterOptions?: (options: Option_2[], state: unknown) => Option_2[];
+}
+
+export declare interface DFCheckboxProps {
+    name?: string;
+    label: string;
+    required?: boolean;
+    checked?: boolean;
+    onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
+    disabled?: boolean;
+    error?: boolean;
+    helperText?: string;
+    size?: ComponentSize;
+    onBlur?: () => void;
+    ref?: React.Ref<unknown>;
+}
+
+export declare interface DFDatePickerProps {
+    value?: Date | null;
+    onChange?: (date: Date | null) => void;
+    label?: string;
+    disabled?: boolean;
+    error?: boolean;
+    helperText?: string;
+    minDate?: Date;
+    maxDate?: Date;
+    required?: boolean;
+    includeTime?: boolean;
+    format?: string;
+    size?: ComponentSize;
+    ref?: React.Ref<HTMLInputElement>;
+}
+
+export declare interface DFDateRange {
+    start: Date | null;
+    end: Date | null;
+}
+
+export declare interface DFDateRangePickerProps {
+    value?: DFDateRange;
+    onChange?: (range: DFDateRange) => void;
+    label?: string;
+    disabled?: boolean;
+    error?: boolean;
+    helperText?: string;
+    minDate?: Date;
+    maxDate?: Date;
+    required?: boolean;
+    includeTime?: boolean;
+    format?: string;
+    size?: ComponentSize;
+}
+
+export declare interface DFFileUploadProps {
+    value?: File | File[] | null;
+    onChange?: (files: File | File[] | null) => void;
+    onBlur?: () => void;
+    multiple?: boolean;
+    accept?: string;
+    label?: string;
+    disabled?: boolean;
+    error?: boolean;
+    helperText?: string;
+    required?: boolean;
+    ref?: React.Ref<HTMLInputElement>;
+}
+
+export declare interface DFNumberFieldProps {
+    name?: string;
+    value?: number | null;
+    onValueChange?: (value: number | null) => void;
+    onBlur?: () => void;
+    label?: React.ReactNode;
+    required?: boolean;
+    placeholder?: string;
+    helperText?: React.ReactNode;
+    error?: boolean;
+    disabled?: boolean;
+    min?: number;
+    max?: number;
+    step?: number;
+    size?: ComponentSize;
+    ref?: React.Ref<HTMLInputElement>;
+}
+
+export declare interface DFRadioGroupProps {
+    name?: string;
+    label?: string;
+    required?: boolean;
+    options: {
+        label: string;
+        value: string;
+    }[];
+    row?: boolean;
+    error?: boolean;
+    helperText?: string;
+    disabled?: boolean;
+    size?: ComponentSize;
+    value?: string;
+    onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
+    onBlur?: () => void;
+    ref?: React.Ref<unknown>;
+}
+
+export declare interface DFSelectProps {
+    name?: string;
+    value?: string | number | readonly string[];
+    onChange?: (event: {
+        target: {
+            value: string;
+        };
+    }) => void;
+    onBlur?: () => void;
+    label?: React.ReactNode;
+    options: Option_2[];
+    size?: ComponentSize;
+    ref?: React.Ref<unknown>;
+}
+
+export declare interface DFSwitchProps {
+    name?: string;
+    label: string;
+    required?: boolean;
+    checked?: boolean;
+    onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
+    disabled?: boolean;
+    error?: boolean;
+    helperText?: string;
+    size?: ComponentSize;
+    onBlur?: () => void;
+    ref?: React.Ref<unknown>;
+}
+
+export declare type DFTextFieldProps = TextFieldProps;
+
+export declare function DynamicForm<T extends Record<string, unknown>>({ schema, onSubmit, mode, defaultValues, apiClient: apiClientOverride, size: sizeOverride, sectionSlotProps, children, }: DynamicFormProps<T>): JSX.Element;
+
+declare interface DynamicFormProps<T extends Record<string, unknown>> {
+    schema: FormSchema;
+    onSubmit: (data: T, labelMap: LabelMap) => void | Promise<void>;
+    mode?: FormMode;
+    defaultValues?: Partial<T>;
+    apiClient?: ApiClient;
+    size?: ComponentSize;
+    sectionSlotProps?: SectionSlotProps;
+    children?: React.ReactNode | ((formState: FormState) => React.ReactNode);
+}
+
+export declare interface DynamicFormsContextValue {
+    apiClient: ApiClient;
+    components: UIComponents;
+    notifications: NotificationCallbacks;
+    size?: ComponentSize;
+    sectionSlotProps?: SectionSlotProps;
+}
+
+export declare function DynamicFormsProvider({ apiClient, components, size, sectionSlotProps, onError, children, }: DynamicFormsProviderProps): JSX.Element;
+
+declare interface DynamicFormsProviderProps {
+    apiClient: ApiClient;
+    components?: Partial<UIComponents>;
+    size?: ComponentSize;
+    sectionSlotProps?: SectionSlotProps;
+    onError?: (message: string) => void;
+    children: React.ReactNode;
+}
+
+/**
+ * Evaluates a condition against form values
+ */
+export declare function evaluateCondition(condition: Condition, values: Record<string, unknown>): boolean;
+
+/**
+ * Extracts default values from form schema
+ * Sets type-appropriate defaults to avoid "undefined" validation errors
+ */
+export declare function extractDefaultValues(schema: FormSchema): Record<string, unknown>;
+
+/**
+ * Extracts field names that options depend on
+ */
+export declare function extractOptionsDependencies(source: OptionsSource): string[];
+
+declare type FieldComponent = ComponentType<FieldComponentProps>;
+
+declare interface FieldComponentProps {
+    name: string;
+    config: FieldConfig;
+    disabled?: boolean;
+}
+
+export declare type FieldConfig = TextFieldConfig | NumberFieldConfig | SelectFieldConfig | AutocompleteFieldConfig | CheckboxFieldConfig | RadioFieldConfig | DateFieldConfig | FileFieldConfig;
+
+export declare type FieldType = 'text' | 'password' | 'email' | 'number' | 'textarea' | 'select' | 'multiselect' | 'autocomplete' | 'checkbox' | 'radio' | 'switch' | 'date' | 'dateRange' | 'file';
+
+export declare interface FileFieldConfig extends BaseFieldConfig {
+    type: 'file';
+    accept?: string;
+    maxSize?: number;
+    multiple?: boolean;
+}
+
+/**
+ * Formats file size in bytes to human-readable format
+ *
+ * @param bytes - File size in bytes
+ * @returns Formatted string with appropriate unit (KB, MB, GB)
+ *
+ * @example
+ * formatFileSize(1024) // "1.00 KB"
+ * formatFileSize(1536) // "1.50 KB"
+ * formatFileSize(1048576) // "1.00 MB"
+ * formatFileSize(5242880) // "5.00 MB"
+ */
+export declare function formatFileSize(bytes: number): string;
+
+export declare class FormErrorBoundary extends Component<Props, State> {
+    constructor(props: Props);
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
+    handleReset: () => void;
+    render(): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | ReactPortal | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | JSX.Element | null | undefined;
+}
+
+/**
+ * Defines a single row in the form layout grid.
+ * Each row can contain one or more sections rendered side-by-side.
+ */
+export declare interface FormLayoutRow {
+    /** Section IDs to place in this row */
+    sections: string[];
+    /** Number of grid columns (defaults to sections.length) */
+    columns?: number;
+}
+
+export declare type FormMode = 'edit' | 'disabled';
+
+export declare interface FormSchema {
+    sections: Section[];
+    fields: Record<string, FieldConfig>;
+    /**
+     * Optional layout configuration for arranging sections in a grid.
+     * Each entry defines a row with one or more sections side-by-side.
+     * If omitted, sections render sequentially (backward compatible).
+     *
+     * @example
+     * layout: [
+     *   { sections: ['credentials', 'personalInfo'] }, // 2 columns
+     *   { sections: ['preferences'] },                 // full width
+     * ]
+     */
+    layout?: FormLayoutRow[];
+}
+
+export declare interface FormState {
+    isValid: boolean;
+    isSubmitting: boolean;
+}
+
+export declare function isEmpty(value: unknown): boolean;
+
+export declare type LabelMap = Record<string, Record<string | number, string>>;
+
+export declare interface NotificationCallbacks {
+    onError?: (message: string) => void;
+}
+
+export declare interface NumberFieldConfig extends BaseFieldConfig {
+    type: 'number';
+    min?: number;
+    max?: number;
+    step?: number;
+}
+
+declare interface Option_2 {
+    value: string | number;
+    label: string;
+    disabled?: boolean;
+}
+export { Option_2 as Option }
+
+export declare interface OptionsSource {
+    apiUrl: string;
+    queryParams?: QueryParam[];
+    valueKey?: string;
+    labelKey?: string;
+}
+
+export declare interface OrCondition {
+    or: Condition[];
+}
+
+declare interface Props {
+    children: ReactNode;
+    fallback?: ReactNode;
+    onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+}
+
+export declare interface QueryParam {
+    key: string;
+    dependsOn?: string;
+    value?: string;
+    dependsOnInput?: boolean;
+}
+
+export declare interface RadioFieldConfig extends BaseFieldConfig {
+    type: 'radio';
+    options?: Option_2[];
+    optionsSource?: OptionsSource;
+    direction?: 'row' | 'column';
+}
+
+export declare function registerFieldComponent(type: FieldType, component: FieldComponent): void;
+
+export declare interface RequestConfig {
+    params?: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+
+export declare interface Section {
+    id: string;
+    title?: string;
+    description?: string;
+    fields: string[];
+}
+
+export declare interface SectionSlotProps {
+    root?: {
+        sx?: SxProps<Theme>;
+    };
+    title?: {
+        sx?: SxProps<Theme>;
+    };
+    description?: {
+        sx?: SxProps<Theme>;
+    };
+    content?: {
+        sx?: SxProps<Theme>;
+    };
+}
+
+export declare interface SelectFieldConfig extends BaseFieldConfig {
+    type: 'select' | 'multiselect';
+    options?: Option_2[];
+    optionsSource?: OptionsSource;
+    initialOptions?: Option_2[];
+}
+
+export declare interface SimpleCondition {
+    field: string;
+    operator: ConditionOperator;
+    value?: unknown;
+}
+
+declare interface State {
+    hasError: boolean;
+    error: Error | null;
+}
+
+export declare interface TextFieldConfig extends BaseFieldConfig {
+    type: 'text' | 'password' | 'email' | 'textarea';
+    autoComplete?: string;
+    rows?: number;
+}
+
+export declare interface UIComponents {
+    TextField: ComponentType<DFTextFieldProps>;
+    NumberField: ComponentType<DFNumberFieldProps>;
+    Select: ComponentType<DFSelectProps>;
+    Autocomplete: ComponentType<DFAutocompleteProps>;
+    Checkbox: ComponentType<DFCheckboxProps>;
+    Switch: ComponentType<DFSwitchProps>;
+    RadioGroup: ComponentType<DFRadioGroupProps>;
+    DatePicker: ComponentType<DFDatePickerProps>;
+    DateRangePicker: ComponentType<DFDateRangePickerProps>;
+    FileUpload: ComponentType<DFFileUploadProps>;
+}
+
+export declare function useAsyncValidation(fieldName: string, config: AsyncValidationConfig | undefined): UseAsyncValidationResult;
+
+declare interface UseAsyncValidationResult {
+    validateDebounced: (value: unknown) => Promise<string | true>;
+    validateImmediate: (value: unknown) => Promise<string | true>;
+}
+
+export declare function useDynamicFormsContext(): DynamicFormsContextValue;
+
+/**
+ * Returns a Set of visible field names based on showIf conditions
+ */
+export declare function useFieldVisibility(schema: FormSchema): Set<string>;
+
+export declare function useOptionsSource(source: OptionsSource | undefined, staticOptions: Option_2[] | undefined, initialOptions?: Option_2[]): UseOptionsSourceResult;
+
+declare interface UseOptionsSourceResult {
+    options: Option_2[];
+    isLoading: boolean;
+    error: Error | null;
+    inputValue?: string;
+    onInputChange?: (event: unknown, value: string, reason: string) => void;
+}
+
+export declare interface ValidationMessages {
+    required?: string;
+    minLength?: string;
+    maxLength?: string;
+    pattern?: string;
+    email?: string;
+    url?: string;
+    hasUppercase?: string;
+    hasLowercase?: string;
+    hasNumber?: string;
+    hasSpecialChar?: string;
+    includes?: string;
+    min?: string;
+    max?: string;
+    invalidDate?: string;
+    minDate?: string;
+    maxDate?: string;
+    invalidRange?: string;
+    maxSize?: string;
+    fileType?: string;
+    minFiles?: string;
+    maxFiles?: string;
+    matchField?: string;
+    asyncValidation?: string;
+}
+
+export declare interface ValidationRules {
+    required?: boolean;
+    requiredIf?: Condition;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    email?: boolean;
+    url?: boolean;
+    hasUppercase?: boolean | number;
+    hasLowercase?: boolean | number;
+    hasNumber?: boolean | number;
+    hasSpecialChar?: boolean | number;
+    includes?: string;
+    min?: number;
+    max?: number;
+    minDate?: Date;
+    maxDate?: Date;
+    maxSize?: number;
+    minFiles?: number;
+    maxFiles?: number;
+    matchField?: string;
+    asyncValidation?: AsyncValidationConfig;
+    messages?: ValidationMessages;
+}
+
+export { }