easy-forms-core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,637 @@
+/**
+ * Tipos de campos soportados
+ */
+type FieldType = 'text' | 'email' | 'number' | 'password' | 'textarea' | 'select' | 'checkbox' | 'radio' | 'switch' | 'date' | 'file' | 'array' | 'group' | 'custom';
+/**
+ * Tipos de validaciones soportadas
+ */
+type ValidationType = 'required' | 'email' | 'minLength' | 'maxLength' | 'min' | 'max' | 'pattern' | 'custom';
+/**
+ * Validación base
+ */
+interface BaseValidation {
+    type: ValidationType;
+    message?: string;
+}
+/**
+ * Validaciones específicas
+ */
+interface RequiredValidation extends BaseValidation {
+    type: 'required';
+}
+interface EmailValidation extends BaseValidation {
+    type: 'email';
+}
+interface MinLengthValidation extends BaseValidation {
+    type: 'minLength';
+    value: number;
+}
+interface MaxLengthValidation extends BaseValidation {
+    type: 'maxLength';
+    value: number;
+}
+interface MinValidation extends BaseValidation {
+    type: 'min';
+    value: number;
+}
+interface MaxValidation extends BaseValidation {
+    type: 'max';
+    value: number;
+}
+interface PatternValidation extends BaseValidation {
+    type: 'pattern';
+    value: string | RegExp;
+}
+interface CustomValidation extends BaseValidation {
+    type: 'custom';
+    validator: (value: any) => boolean | Promise<boolean>;
+}
+/**
+ * Unión de todas las validaciones
+ */
+type Validation = RequiredValidation | EmailValidation | MinLengthValidation | MaxLengthValidation | MinValidation | MaxValidation | PatternValidation | CustomValidation;
+/**
+ * Campo base
+ */
+interface BaseField {
+    type: FieldType;
+    name: string;
+    label?: string;
+    placeholder?: string;
+    defaultValue?: any;
+    validations?: Validation[];
+    props?: Record<string, any>;
+    disabled?: boolean;
+    hidden?: boolean;
+    description?: string;
+}
+/**
+ * Campo de texto
+ */
+interface TextField extends BaseField {
+    type: 'text' | 'email' | 'password';
+}
+/**
+ * Campo numérico
+ */
+interface NumberField extends BaseField {
+    type: 'number';
+    min?: number;
+    max?: number;
+    step?: number;
+}
+/**
+ * Campo textarea
+ */
+interface TextareaField extends BaseField {
+    type: 'textarea';
+    rows?: number;
+    cols?: number;
+}
+/**
+ * Campo select
+ */
+interface SelectField extends BaseField {
+    type: 'select';
+    options: Array<{
+        label: string;
+        value: any;
+    } | string>;
+    multiple?: boolean;
+}
+/**
+ * Campo checkbox
+ */
+interface CheckboxField extends BaseField {
+    type: 'checkbox';
+    checked?: boolean;
+}
+/**
+ * Campo radio
+ */
+interface RadioField extends BaseField {
+    type: 'radio';
+    options: Array<{
+        label: string;
+        value: any;
+    } | string>;
+}
+/**
+ * Campo switch
+ */
+interface SwitchField extends BaseField {
+    type: 'switch';
+    checked?: boolean;
+}
+/**
+ * Campo date
+ */
+interface DateField extends BaseField {
+    type: 'date';
+    min?: string;
+    max?: string;
+}
+/**
+ * Campo file
+ */
+interface FileField extends BaseField {
+    type: 'file';
+    accept?: string;
+    multiple?: boolean;
+}
+/**
+ * Campo array
+ */
+interface ArrayField extends BaseField {
+    type: 'array';
+    itemSchema: FormSchema;
+    minItems?: number;
+    maxItems?: number;
+}
+/**
+ * Campo group
+ */
+interface GroupField extends BaseField {
+    type: 'group';
+    fields: Field[];
+}
+/**
+ * Campo custom
+ */
+interface CustomField extends BaseField {
+    type: 'custom';
+    component: string;
+}
+/**
+ * Unión de todos los tipos de campos
+ */
+type Field = TextField | NumberField | TextareaField | SelectField | CheckboxField | RadioField | SwitchField | DateField | FileField | ArrayField | GroupField | CustomField;
+/**
+ * Step para formularios wizard
+ */
+interface Step {
+    title: string;
+    description?: string;
+    fields: Field[];
+}
+/**
+ * Tipos de temas disponibles
+ */
+type FormTheme = 'plano' | 'tradicional' | 'material' | 'rounded-shadow' | 'lines';
+/**
+ * Colores personalizados del formulario
+ */
+interface FormColors {
+    primary?: string;
+    secondary?: string;
+    error?: string;
+    success?: string;
+    text?: string;
+    border?: string;
+    background?: string;
+}
+/**
+ * Schema del formulario
+ */
+interface FormSchema {
+    fields?: Field[];
+    steps?: Step[];
+}
+/**
+ * Estado del formulario
+ */
+interface FormState {
+    values: Record<string, any>;
+    errors: Record<string, string[]>;
+    touched: Record<string, boolean>;
+    isValid: boolean;
+    isSubmitting: boolean;
+}
+/**
+ * Estado de wizard
+ */
+interface WizardState {
+    currentStep: number;
+    totalSteps: number;
+    completedSteps: number[];
+}
+/**
+ * Evento de submit
+ */
+interface SubmitEventDetail {
+    values: Record<string, any>;
+    isValid: boolean;
+    errors: Record<string, string[]>;
+}
+/**
+ * Evento de change
+ */
+interface ChangeEventDetail {
+    field: string;
+    value: any;
+    values: Record<string, any>;
+}
+/**
+ * Evento de error
+ */
+interface ErrorEventDetail {
+    errors: Record<string, string[]>;
+    field?: string;
+}
+/**
+ * Evento de step change
+ */
+interface StepChangeEventDetail {
+    currentStep: number;
+    previousStep: number;
+    totalSteps: number;
+}
+/**
+ * Componente personalizado para inyección
+ */
+type CustomComponent = (props: {
+    field: Field;
+    value: any;
+    error?: string;
+    onChange: (value: any) => void;
+    onBlur: () => void;
+}) => HTMLElement | null;
+/**
+ * Registro de componentes personalizados
+ */
+interface ComponentRegistry {
+    [key: string]: CustomComponent;
+}
+
+declare const BrowserHTMLElement: {
+    new (): HTMLElement;
+    prototype: HTMLElement;
+};
+/**
+ * Web Component principal EasyForm
+ */
+declare class EasyForm extends BrowserHTMLElement {
+    private stateManager;
+    protected shadow: ShadowRoot;
+    private customComponents;
+    private isRendering;
+    static get observedAttributes(): string[];
+    constructor();
+    /**
+     * Obtiene el schema
+     */
+    get schema(): FormSchema | null;
+    /**
+     * Establece el schema
+     */
+    set schema(value: FormSchema | null);
+    /**
+     * Se llama cuando el componente se conecta al DOM
+     */
+    connectedCallback(): void;
+    /**
+     * Se llama cuando un atributo cambia
+     */
+    attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
+    /**
+     * Maneja el cambio de schema
+     */
+    private handleSchemaChange;
+    /**
+     * Renderiza el formulario
+     */
+    private render;
+    /**
+     * Preserva los valores actuales del DOM antes de re-renderizar
+     * Retorna un objeto con los valores preservados
+     */
+    private preserveCurrentValues;
+    /**
+     * Renderiza campos normales
+     */
+    private renderFields;
+    /**
+     * Renderiza un campo
+     */
+    private renderField;
+    /**
+     * Renderiza un grupo de campos
+     */
+    private renderGroup;
+    /**
+     * Renderiza un array dinámico
+     */
+    private renderArray;
+    /**
+     * Renderiza un campo custom
+     */
+    private renderCustom;
+    /**
+     * Renderiza wizard
+     */
+    private renderWizard;
+    /**
+     * Maneja el cambio de un campo
+     */
+    private handleFieldChange;
+    /**
+     * Maneja el blur de un campo
+     */
+    private handleFieldBlur;
+    /**
+     * Actualiza solo un campo específico sin re-renderizar todo el formulario
+     */
+    private updateSingleField;
+    /**
+     * Busca un campo por nombre en el schema
+     */
+    private findFieldInSchema;
+    /**
+     * Maneja el submit del formulario
+     */
+    private handleSubmit;
+    /**
+     * Emite evento de error
+     */
+    private emitError;
+    /**
+     * Emite evento de cambio de step
+     */
+    private emitStepChange;
+    /**
+     * Registra componentes personalizados
+     */
+    registerComponents(components: ComponentRegistry): void;
+    /**
+     * Obtiene el tema del formulario
+     */
+    get theme(): FormTheme;
+    /**
+     * Establece el tema del formulario
+     */
+    set theme(value: FormTheme);
+    /**
+     * Obtiene los colores personalizados
+     */
+    get colors(): FormColors | null;
+    /**
+     * Establece los colores personalizados
+     */
+    set colors(value: FormColors | null);
+    /**
+     * Configura estilos básicos
+     */
+    private setupStyles;
+}
+
+/**
+ * Gestor de estado del formulario
+ */
+declare class StateManager {
+    private state;
+    private wizardState;
+    private schema;
+    private parser;
+    private validator;
+    constructor();
+    /**
+     * Crea el estado inicial
+     */
+    private createInitialState;
+    /**
+     * Inicializa el schema
+     */
+    initializeSchema(schema: FormSchema): void;
+    /**
+     * Inicializa los valores por defecto
+     */
+    private initializeValues;
+    /**
+     * Inicializa el valor de un campo
+     */
+    private initializeFieldValue;
+    /**
+     * Inicializa el estado del wizard
+     */
+    private initializeWizard;
+    /**
+     * Obtiene el estado actual
+     */
+    getState(): FormState;
+    /**
+     * Obtiene el estado del wizard
+     */
+    getWizardState(): WizardState | null;
+    /**
+     * Obtiene un valor del formulario
+     */
+    getValue(fieldName: string): any;
+    /**
+     * Establece un valor
+     */
+    setValue(fieldName: string, value: any): Promise<void>;
+    /**
+     * Establece un valor sin validar (útil para preservar valores durante re-renderizado)
+     */
+    setValueWithoutValidation(fieldName: string, value: any): void;
+    /**
+     * Valida un campo específico
+     */
+    validateField(fieldName: string): Promise<void>;
+    /**
+     * Valida todo el formulario
+     */
+    validateForm(): Promise<Record<string, string[]>>;
+    /**
+     * Actualiza la validez del formulario
+     */
+    private updateValidity;
+    /**
+     * Marca un campo como touched
+     */
+    setTouched(fieldName: string): void;
+    /**
+     * Obtiene los errores de un campo
+     */
+    getErrors(fieldName: string): string[];
+    /**
+     * Obtiene todos los errores
+     */
+    getAllErrors(): Record<string, string[]>;
+    /**
+     * Resetea el formulario
+     */
+    reset(): void;
+    /**
+     * Avanza al siguiente step del wizard
+     */
+    nextStep(): boolean;
+    /**
+     * Retrocede al step anterior del wizard
+     */
+    previousStep(): boolean;
+    /**
+     * Va a un step específico
+     */
+    goToStep(stepIndex: number): boolean;
+    /**
+     * Marca un step como completado
+     */
+    completeStep(stepIndex: number): void;
+    /**
+     * Establece el estado de submitting
+     */
+    setSubmitting(isSubmitting: boolean): void;
+    /**
+     * Obtiene los campos del step actual
+     */
+    getCurrentStepFields(): Field[];
+}
+
+/**
+ * Motor de validaciones
+ */
+declare class ValidationEngine {
+    /**
+     * Valida un campo con todas sus validaciones
+     */
+    validateField(field: Field, value: any): Promise<string[]>;
+    /**
+     * Valida un valor con una validación específica
+     */
+    private validateValue;
+    /**
+     * Valida campo requerido
+     */
+    private validateRequired;
+    /**
+     * Valida email
+     */
+    private validateEmail;
+    /**
+     * Valida longitud mínima
+     */
+    private validateMinLength;
+    /**
+     * Valida longitud máxima
+     */
+    private validateMaxLength;
+    /**
+     * Valida valor mínimo
+     */
+    private validateMin;
+    /**
+     * Valida valor máximo
+     */
+    private validateMax;
+    /**
+     * Valida patrón regex
+     */
+    private validatePattern;
+    /**
+     * Valida con función personalizada
+     */
+    private validateCustom;
+    /**
+     * Obtiene mensaje por defecto para una validación
+     */
+    private getDefaultMessage;
+    /**
+     * Valida todos los campos de un formulario
+     */
+    validateForm(fields: Field[], values: Record<string, any>): Promise<Record<string, string[]>>;
+}
+
+/**
+ * Parser del schema JSON
+ */
+declare class SchemaParser {
+    /**
+     * Parsea y valida un schema
+     */
+    parse(schema: FormSchema): ParsedSchema;
+    /**
+     * Normaliza y valida campos
+     */
+    private normalizeFields;
+    /**
+     * Valida el tipo de campo
+     */
+    private validateFieldType;
+    /**
+     * Aplica valores por defecto a un campo
+     */
+    private applyDefaults;
+    /**
+     * Obtiene todos los campos de un schema (incluyendo nested)
+     */
+    getAllFields(schema: FormSchema): Field[];
+}
+/**
+ * Schema parseado
+ */
+interface ParsedSchema {
+    fields: Field[];
+    steps?: Step[];
+    isWizard: boolean;
+}
+
+/**
+ * Obtiene los colores con valores por defecto
+ */
+declare function getColors(colors?: FormColors): Required<FormColors>;
+/**
+ * Genera estilos CSS para un tema específico
+ */
+declare function getThemeStyles(theme: FormTheme, colors: Required<FormColors>): string;
+
+/**
+ * Utilidades generales
+ */
+/**
+ * Convierte un valor a string para atributos HTML
+ */
+declare function attributeValue(value: any): string;
+/**
+ * Parsea un valor desde un atributo HTML
+ */
+declare function parseAttributeValue(value: string | null): any;
+/**
+ * Genera un ID único
+ */
+declare function generateId(prefix?: string): string;
+/**
+ * Obtiene el valor anidado de un objeto usando notación de punto
+ */
+declare function getNestedValue(obj: Record<string, any>, path: string): any;
+/**
+ * Establece un valor anidado en un objeto usando notación de punto
+ */
+declare function setNestedValue(obj: Record<string, any>, path: string, value: any): void;
+/**
+ * Valida si un email es válido
+ */
+declare function isValidEmail(email: string): boolean;
+/**
+ * Sanitiza un string para usar como ID de HTML
+ */
+declare function sanitizeId(str: string): string;
+
+/**
+ * Factory para crear inputs
+ */
+declare function createInput(field: Field, value: any, error: string | undefined, onChange: (value: any) => void, onBlur: () => void): HTMLElement;
+/**
+ * Registra un componente personalizado
+ */
+declare function registerComponent(type: string, component: CustomComponent): void;
+/**
+ * Registra múltiples componentes
+ */
+declare function registerComponents(components: Record<string, CustomComponent>): void;
+/**
+ * Obtiene un componente personalizado
+ */
+declare function getCustomComponent(type: string): CustomComponent | undefined;
+
+export { type ArrayField, type BaseField, type BaseValidation, type ChangeEventDetail, type CheckboxField, type ComponentRegistry, type CustomComponent, type CustomField, type CustomValidation, type DateField, EasyForm, type EmailValidation, type ErrorEventDetail, type Field, type FieldType, type FileField, type FormColors, type FormSchema, type FormState, type FormTheme, type GroupField, type MaxLengthValidation, type MaxValidation, type MinLengthValidation, type MinValidation, type NumberField, type PatternValidation, type RadioField, type RequiredValidation, SchemaParser, type SelectField, StateManager, type Step, type StepChangeEventDetail, type SubmitEventDetail, type SwitchField, type TextField, type TextareaField, type Validation, ValidationEngine, type ValidationType, type WizardState, attributeValue, createInput, generateId, getColors, getCustomComponent, getNestedValue, getThemeStyles, isValidEmail, parseAttributeValue, registerComponent, registerComponents, sanitizeId, setNestedValue };