easy-forms-core 1.0.0

package/README.md

@@ -0,0 +1,133 @@
+# EasyForms
+
+EasyForms es una librería agnóstica de framework para construir formularios dinámicos a partir de JSON usando Web Components.
+
+Permite crear formularios completos únicamente describiendo un schema JSON.
+
+## Compatibilidad
+
+Funciona en:
+- Vue
+- React
+- Svelte
+- Nuxt
+- Next
+- Astro
+- HTML vanilla
+
+No depende de ningún framework.
+
+## Instalación
+
+```bash
+bun add easy-forms
+# o
+npm install easy-forms
+# o
+pnpm add easy-forms
+```
+
+## Uso Básico
+
+### HTML Vanilla
+
+```html
+<easy-form id="form"></easy-form>
+```
+
+```javascript
+import 'easy-forms'
+
+const form = document.querySelector('#form')
+
+form.schema = {
+  fields: [
+    {
+      type: 'text',
+      name: 'email',
+      label: 'Email',
+      validations: [
+        { type: 'required' },
+        { type: 'email' }
+      ]
+    }
+  ]
+}
+
+form.addEventListener('submit', (event) => {
+  console.log(event.detail)
+})
+```
+
+### React
+
+```tsx
+import 'easy-forms'
+
+function MyForm() {
+  return (
+    <easy-form
+      schema={{
+        fields: [
+          { type: 'text', name: 'name', label: 'Nombre' }
+        ]
+      }}
+    />
+  )
+}
+```
+
+### Vue
+
+```vue
+<script setup>
+import 'easy-forms'
+
+const schema = {
+  fields: [
+    { type: 'text', name: 'name', label: 'Nombre' }
+  ]
+}
+</script>
+
+<template>
+  <easy-form :schema="schema" />
+</template>
+```
+
+## Características
+
+- Web Component nativo
+- Escrito en TypeScript
+- JSON → Form automático
+- Validaciones integradas
+- Steps / wizard forms
+- Formularios anidados
+- Arrays dinámicos
+- Componentes visuales personalizables
+- Eventos de submit, change y error
+- Testing friendly
+- Listo para producción
+
+## Desarrollo
+
+```bash
+# Instalar dependencias
+bun install
+
+# Desarrollo con watch
+bun run dev
+
+# Desarrollo de documentación
+bun run dev:docs
+
+# Build
+bun run build
+
+# Tests
+bun test
+```
+
+## Licencia
+
+MIT

package/dist/easy-form.d.ts

@@ -0,0 +1,338 @@
+/**
+ * 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[];
+}
+/**
+ * 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;
+}
+
+export { EasyForm };